# Software architecture diagram

Architecture diagrams go stale faster than any other kind, because they are drawn once for a review and then never opened again. Keeping the diagram on the page it documents, editable by whoever is changing the system, is most of the fix.

The rest is discipline: one diagram per question.

---

## When to reach for one

* Design reviews, where the diagram is the proposal.
* Documenting a system that already exists and currently lives in one person's head.
* Comparing options, where two diagrams side by side beat two paragraphs.

---

## How to draw it in Capable

| **Route**     | **Use when**                                        |
| ------------- | --------------------------------------------------- |
| D2 or Mermaid | Text, so it diffs in review and updates in seconds. |
| draw.io       | Positional meaning, or provider icons.              |
| C4-PlantUML   | You want the zoom-level discipline of C4.           |

---

## A worked example

A three-tier system in D2, which lays itself out:

![Software architecture diagram](https://help.gocapable.com/images/att1418657814.svg)

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

```
web: Web app {
  shape: rectangle
}
api: API {
  shape: rectangle
}
worker: Worker
db: Postgres {
  shape: cylinder
}
queue: Redis queue {
  shape: queue
}

web -> api: HTTPS
api -> db: SQL
api -> queue: enqueue job
queue -> worker: dequeue
worker -> db: SQL
```

---

## A few things that catch people out

* Date the diagram, or better, keep it on the page that changes when the system does.
* An arrow with no label is a question waiting to be asked. Say what flows and how.
* Draw the boundary. What is inside your control and what is not is usually the most useful line on the page.

---

## Related

[Microservices architectureService boundaries, and which calls are synchronous.](https://help.gocapable.com/diagrams/microservices-architecture.html)

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

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

---

_Cheap to change means it stays true._