# 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:

![Microservices architecture](https://help.gocapable.com/images/att1439236141.svg)

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.

---

## Related

[Dependency graphGenerated, not drawn by hand.](https://help.gocapable.com/diagrams/dependency-graph.html)

[Git branching diagramExplaining a branching model without a whiteboard.](https://help.gocapable.com/diagrams/git-branching-diagram.html)

[ExamplesWorking diagrams you can copy.](https://help.gocapable.com/diagrams/examples.html)

---

_Cheap to change means it stays true._