Software architecture diagram

Updated
View as text
Open in Confluence
Open in ChatGPT Open in Claude

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

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.

Cheap to change means it stays true.