Microservices architecture

The useful microservice diagram is not the one showing every service. It is the one showing which calls are synchronous, because that is where cascading failure lives.

Draw asynchronous edges differently from synchronous ones and the diagram starts answering real questions.

#When to reach for one

Reliability reviews: which service takes the others down with it.
Onboarding, where the service map is the mental model.
Planning a migration or an extraction, where the boundary is the debate.

#How to draw it in Capable

Route	Use when
Mermaid or D2	Text, so it can live next to the service list and be updated with it.
draw.io	Larger maps where grouping and position carry meaning.

#A worked example

Solid arrows are synchronous calls, dashed ones go through a queue:

The source, which you can paste into a new diagram and edit:

flowchart LR
  GW[API gateway] --> ORD[Order service]
  GW --> CAT[Catalogue service]
  ORD --> PAY[Payment service]
  ORD -. order.placed .-> QUEUE[(Event bus)]
  QUEUE -. subscribes .-> SHIP[Shipping service]
  QUEUE -. subscribes .-> MAIL[Notification service]
  ORD --> ODB[(Orders DB)]
  CAT --> CDB[(Catalogue DB)]

#A few things that catch people out

Two services sharing a database are one service with extra steps. The diagram makes that obvious.
Show the queue as a node. Hiding it behind a dashed line loses the fact that it can back up.
Above roughly fifteen services, draw domains rather than services, and link out to per-domain diagrams.

Dependency graph

Generated, not drawn by hand.

Git branching diagram

Explaining a branching model without a whiteboard.

Examples

Working diagrams you can copy.

Cheap to change means it stays true.