Microservices, drawn honestly
Every microservice diagram looks the same and almost none of them answer the only question that matters: can any one of these be deployed on its own? Two arrangements of the same four services - one that can, one that cannot.
8 min readUML 2.5.122 of 23
01The question a microservice diagram must answer
Not "what services are there" - a list does that, and the list is usually in the repository names. The question is: can any one of these be deployed on its own? Everything people hope to get from microservices - independent releases, independent scaling, a team that can ship without a coordination meeting - follows from the answer being yes, and no other property of the drawing matters if it is no.
A component diagram answers it, provided you draw the right things. Every deployable service is a component; every published contract is an interface; every event is a «signal». Then cover a service with your hand: if what remains fully specifies its replacement, that service can be released on its own schedule.
02Two kinds of arrow, deliberately
On the figure above, the gateway depends on IOrders - a synchronous contract, because the gateway cannot answer the user without an order. Shipping and billing point at OrderPlaced, a signal the order service sends and does not wait on.
Drawing the two differently is the entire value of the picture. The synchronous edges are where availability composes: if the order service is down, the gateway returns an error. The event edges are where it does not: shipping being down delays a parcel and takes nothing else with it. A diagram that draws both as plain arrows has erased the distinction that decides how the system fails.
03The arrangement to recognise
This is a distributed monolith, and it is the most common shape in production. Nothing on it is illegal, nothing is badly named, and it will pass review because it looks like every other microservice diagram. What it says, if you read the arrows rather than the boxes, is that the four services must be deployed together, tested together and be up together - so the team has taken on every cost of distribution and kept every constraint of a monolith.
The tell is countable: the number of synchronous hops on one request. One is fine. Two is usually fine. Three or more and the availability of the whole is the product of the parts, so four services at 99.9% each answer about 99.6% together - which is three hours a month of nobody being able to order anything.
The fixes are visible on the same drawing. Let orders publish an event and let pricing and inventory react to it. Or merge two of the boxes, which is a legitimate answer that rarely gets proposed. Or cache what pricing needs, so the hop stops being on the request path. All three are edits to this diagram, which is why drawing it before building is worth the twenty minutes.
In one line each
- 01One component per deployable service, one interface per published contract, one signal per event.
- 02Draw synchronous and asynchronous coupling differently - it is how the system fails.
- 03Synchronous when the caller needs the answer; an event when it does not.
- 04Count synchronous hops per request: three or more is a distributed monolith.
- 05Availability multiplies along a synchronous chain, and four nines become three.
- 06Cover any service: what remains must specify its replacement, or it cannot ship alone.
The notation is covered in the component diagram guide, and five more arrangements - including the two-way cycle this article does not repeat - are in component diagram examples.
04Common questions
How do you draw microservices in UML?
As components, one per deployable service, with an interface for every published contract and a signal for every event. What makes it a microservice diagram rather than a module diagram is that each box could be released on its own day, which is a claim the interfaces around it either support or contradict.
How can I tell a distributed monolith from a diagram?
Follow the synchronous arrows and count the hops on one request. If a single user action crosses three or more services that must all be up, you have distributed a monolith rather than decomposed one, and the diagram has told you before production did.
Should services talk synchronously or through events?
Synchronously when the caller cannot proceed without the answer, and through an event when it can. Drawing the two differently - an interface for calls, a signal for events - turns that judgement into something a reviewer can see and disagree with rather than a convention buried in the code.
Where does the database go in a microservices diagram?
One per service, and off this diagram. A component view is about the contracts between services, and drawing five databases adds five boxes that all say the same thing; where they run belongs on the deployment diagram, and what they hold belongs on each service's own model.
Related reading