Level 1
The System Context diagram
One box for your system, the people who use it, and the systems it depends on. It is the only architecture diagram that a product manager, a security reviewer and a new engineer can all read on their first day.
What it is for
A System Context diagram sets the scope. It answers: what is this thing, who uses it, and what does it need from the outside world? Everything internal is deliberately hidden — no databases, no services, no queues.
Because it hides internals, it is also the most stable diagram you own. A team can rewrite its entire backend without changing Level 1, which is exactly what makes it worth putting in the README.
What goes on it
- The system — A single box in the middle. No internal structure, however tempting.
- People — Actors and roles, not named individuals: "Customer", "Support agent", "Back-office analyst".
- External systems — Anything you integrate with but do not own — payment providers, identity providers, the legacy mainframe, the partner API.
- Labelled relationships — "Customer views account balances", "System sends settlement files to the clearing house, SFTP nightly".
A worked example
Take an internet banking system. Level 1 has exactly four boxes and it takes ten minutes to draw:
Drawing the boundary honestly
The boundary is an ownership question, not a network question. Inside the box is what your team can change without asking anyone. Outside is everything you can only negotiate with.
Teams get this wrong in both directions. Swallowing a system you do not own hides a real dependency risk. Pushing out a system you do own — because a different team maintains it — hides the fact that you are one organisation shipping one product.
Failure modes
- Leaking internals — A database on Level 1 means you have drawn a container diagram badly.
- Unlabelled arrows — Direction without meaning. "A → B" is not information.
- Org chart in disguise — Boxes named after teams rather than systems, so the diagram rots at the next reorg.
- Too many boxes — If Level 1 has fifteen external systems, your scope is probably several systems.
Frequently asked
Should a database appear on a System Context diagram?
Only if it is a system you do not own and integrate with as an external dependency — a shared data warehouse, for example. Your own application database belongs on the Container diagram.
How many boxes should a System Context diagram have?
Usually between four and ten. Beyond that, either the scope is too broad or several external systems can be grouped by the capability they provide.
The guide
The rest of the guide
Eight short pages covering the four levels, the notation, the comparisons people ask about, and the tooling decisions that only hurt six months in.
Level 1
The System Context diagram
One box for your system, the people who use it, and the systems it depends on. It is the only architecture diagram that a product manager, a security reviewer and a new engineer can all read on their first day.
Level 2
The Container diagram
The separately deployable pieces inside your system and the technology each one is built with. If a team draws only one architecture diagram, this is the one that earns its keep.
Level 3
The Component diagram
The major building blocks inside one container, what each is responsible for, and how they collaborate. Drawn per container, and only for the containers that are genuinely hard.
Level 4
The Code diagram
Classes, interfaces and their relationships inside a single component. The level almost everybody draws first and almost nobody should maintain by hand.
Comparison
C4 vs UML, ArchiMate and "boxes and lines"
C4 is not competing with UML — it is solving a different problem. Knowing which problem each one solves is what stops an architecture review turning into a notation argument.
Comparison
C4 and arc42
These two get compared as if you had to pick one. You do not: arc42 is the shape of the document, C4 is what goes in the picture. Teams that understand that use both and stop arguing.
Comparison
Structurizr, and when to use something else
Structurizr is the reference implementation of C4, written by the person who invented C4. That is a real argument in its favour and worth saying before any comparison starts.
Practice
C4 with PlantUML: diagrams as text
Text-based diagrams review like code, diff like code and survive like code. Here is how PlantUML fits a C4 model — and where writing everything by hand stops paying.
Comparison
C4 tools compared
Drawing tools, diagrams-as-code and modelling tools solve different halves of the problem. The right choice depends on whether you are producing pictures or maintaining a model — and on whether the model has to stay on your own machine.
See it as a model rather than a picture
Viaduct puts all four levels in one navigable model with the documentation attached. It runs locally in the browser — no account needed.