Documenting architecture: the C4 model and architecture decision records

The problem with architecture diagrams

Many diagrams mix everything: users, servers, code modules and network links in one tangle of boxes and arrows with no key. Readers cannot tell what a box means or what an arrow does. The C4 model, created by Simon Brown, fixes this with a small set of abstractions and four levels of zoom. It is notation-independent: you can draw it on a whiteboard, in a diagram tool, or generate it from text with tools such as Structurizr or PlantUML.

The four levels

In C4, a "container" means any running unit, not only a Docker container. A deployment diagram can be added to show where containers run: which servers, cloud services, network zones and regions. For network and security engineers this view is often the most useful, as it shows trust boundaries and which flows cross firewalls.

Drawing good C4 diagrams

• Give every diagram a title and a key explaining shapes, colours and line styles.
• Label each box with name, type and a short responsibility, for example "Orders API, .NET, handles order requests".
• Label every arrow with what flows and how, for example "Reads customer data, HTTPS/JSON".
• Keep each diagram to roughly 20 boxes or fewer; split it if it grows.
• Store diagram source next to the code so it changes with it ("diagrams as code").

Architecture decision records

Diagrams show what exists; they rarely explain why. An architecture decision record (ADR) is a short text file that captures one significant decision. The format popularised by Michael Nygard is widely copied:

# ADR 0007: Use managed PostgreSQL for the orders database

Status: Accepted (2026-03-14)

Context:
  The orders service needs a relational database with point-in-time
  recovery. The team has strong PostgreSQL skills but no DBA.

Decision:
  Use the cloud provider's managed PostgreSQL service in two zones.

Consequences:
  + Backups, patching and failover are handled by the provider.
  - Some extensions are unavailable; costs rise with storage.
  - Ties the service more closely to one cloud provider.

Keep ADRs numbered in a folder in the repository. Once accepted, do not rewrite them; write a new ADR that supersedes the old one. Over time this becomes a readable history of the system's design, which is invaluable for new team members, auditors and incident reviews.

Tip: record decisions that are hard to reverse or that people will question later, such as choice of database, identity provider, network segmentation or hosting region. Skip trivial ones.