Most architecture diagrams fail for one reason: they mix abstraction levels. A single picture shows an entire third-party platform as one box, a microservice as another box the same size, and a specific class as a third. The viewer has no way to know what any box represents, so the diagram conveys a vague sense of complexity and nothing else.
The C4 model's contribution is simply insisting that each diagram picks one level and stays there.
What changed in 2026
- Diagrams as code became the default. Text-based diagram definitions living in the repository and rendering in documentation displaced drawing tools, mainly because they stay current.
- The top two levels got emphasized. Practitioner guidance converged on context and container diagrams carrying nearly all the value, with lower levels rarely justified.
- Generated diagrams improved. Tooling deriving container diagrams from infrastructure definitions and service registries reduced the manual maintenance burden.
- AI assistants became a consumer. Coding agents reading a repository benefit from an accurate high-level diagram in the same way a new engineer does.
The four levels
| Level |
Shows |
Audience |
Worth drawing |
| Context |
Your system, its users, and external systems it talks to |
Everyone, including non-technical |
Almost always |
| Container |
Deployable units — services, databases, apps — and how they communicate |
Engineers, operations |
Almost always |
| Component |
Major internal parts of one container |
Engineers on that container |
Occasionally |
| Code |
Classes and their relationships |
Nobody, usually |
Rarely |
The context diagram is the one most teams do not have and most benefit from. One box for your system, boxes around it for the people who use it and the external systems it depends on, arrows labelled with what flows. It fits on a page, a non-engineer can read it, and it answers the question new joiners actually ask first.
The container diagram is the working document. Every deployable thing, every datastore, every communication path between them, with protocols labelled. This is what people need during an incident, during onboarding, and when planning a change that crosses services.
Below that, diminishing returns set in sharply. A component diagram can help for an unusually complex service. A code-level diagram is almost always worse than reading the code, and it is stale the moment it is drawn.
Keeping them accurate
A diagram that does not match reality is worse than no diagram, because people act on it. The only reliable defence is making the diagram cheap to update and keeping it next to the code.
Text-based diagram definitions in the repository achieve this. They are reviewable in a pull request, so a change that adds a service can update the diagram in the same change. They render in documentation automatically. And they diff meaningfully, which a binary drawing file does not.
Where possible, generate rather than maintain. Container-level structure frequently exists already in infrastructure definitions or service configuration, and deriving the diagram from that source keeps it correct by construction.
Pair the diagrams with written rationale. A diagram shows what the structure is; it cannot show why — that is what architecture decision records capture.
Common mistakes
- Mixing abstraction levels. The failure that makes most diagrams useless.
- Unlabelled arrows. An arrow with no label conveys almost nothing.
- Drawing all four levels. The bottom two rarely earn their maintenance.
- Diagrams in a drawing tool outside the repository. Go stale immediately.
- No context diagram. The one non-engineers can read, most often missing.
- Including every detail at container level. It is a map, not an inventory.
FAQ
Do I need special tooling?
No. Any text-based diagramming syntax that renders in your documentation works. The important properties are version control and reviewability.
How often should diagrams be updated?
With the change that makes them wrong, in the same pull request. Scheduled review catches what slipped through.
Is C4 better than other notations?
Its contribution is the discipline of separated abstraction levels, which is the part that matters. The specific notation is secondary.
What about dynamic behaviour?
C4 describes structure. Sequence diagrams complement it for showing how a specific flow moves through the structure.
Where to go next
For capturing rationale, read architecture decision records. For discovering the domain before drawing it, event storming guide, and for structuring the model itself, DDD aggregates explained.