Software architecture

Architecture diagrams belong beside the decision records that justify them. Keeping both in Confluence means the diagram is updated by the person changing the system rather than by whoever owns the slide deck.

Use text languages for anything that changes, and a canvas only where position genuinely carries meaning.

#When to draw one

Design reviews and architecture decision records.
Onboarding, where the system map is the mental model.
Documenting a system that currently exists only in one person's head.

#What is on the diagram

Element	Meaning
A C4 context diagram	Explaining the system to people outside the team
A C4 container diagram	The everyday architecture diagram
A sequence diagram	Explaining an interaction rather than a structure
A dependency graph	When the question is what depends on what

#A worked example

A container-level view of a small system:

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

flowchart TB
  U([Customer]) --> WEB[Web app]
  WEB --> API[API service]
  API --> DB[(PostgreSQL)]
  API --> Q{{Job queue}}
  Q --> WRK[Worker]
  WRK --> DB
  API --> PAY[Payment provider]
  WRK --> MAIL[Email service]

#A few things that catch people out

Date it, or better, keep it on the page that changes when the system does.
Label the arrows with what flows and how. Unlabelled arrows invite the wrong assumption.
One diagram per question. Trying to show everything is why architecture diagrams go unread.

Operational knowledge

Runbooks that include the picture.

Technical documentation

Diagrams next to the words they illustrate.

Diagram types

Every type, grouped by what it is for.

Diagrams next to the words they explain.