What is the C4 model?
Four levels of zoom over one system, each answering a question the level above it raised - and deliberately no notation of its own, which is the reason it travels between teams.
7 min readC4 model1 of 3
The short answer
- C4 is four levels of zoom over one system - context, containers, components, code - and each level exists to answer one question the level above it raised.
- It is a convention, not a notation. C4 says what belongs on a diagram and leaves the shapes to you, which is why it can be drawn in UML, in ArchiMate, or in boxes and arrows.
- A container is a deployable or runnable thing - an application, a service, a database - not a Docker container. It is the level most teams get value from and the one most often skipped.
- Level 4 is usually not worth drawing by hand. If you want the classes, generate them from the code, where they are already true.
01Four questions, in order#
The C4 model is a set of four diagrams over one system, each one a closer view than the last. Its real contribution is not the drawing - it is the ordering. Each level answers a question, and answering it raises the question the next level exists for.
| Element | Notation | What it means |
|---|---|---|
| 1. System context | One box, plus its people and neighbours | One box for your system, surrounded by the people and the other systems it talks to. No internals at all. The diagram a new joiner and a stakeholder can both read. |
| 2. Containers | Boxes inside the system boundary | That one box, opened. The separately deployable or runnable things - web application, API, database, broker - and the calls between them. |
| 3. Components | Boxes inside one container | One container, opened. The major structural parts inside it and their dependencies. Worth drawing when a container is big enough to argue about. |
| 4. Code | Classes | The classes inside one component, which is a UML class diagram. Generate it or skip it; hand-drawing this level is how a diagram goes stale fastest. |
The audience narrows as you descend. Level 1 is for anybody with an interest in the system, including people who will never read code. Level 4 is for the team, on a week when they are restructuring something. That gradient is the argument for drawing the first two and stopping until somebody asks for more.
02C4 is a convention, not a notation#
This is the part that gets lost. C4 does not define shapes, line styles or relationship semantics. It tells you what belongs on each diagram and who it is for, and then says: draw it however your team already draws things.
The practical consequence is that C4 composes with the notation you have rather than replacing it. A container diagram drawn with UML components is a legal UML diagram and a correct C4 one at the same time. Drawn in ArchiMate, the same content maps onto application components and technology nodes. Both are fine. What is not fine is a diagram whose boxes mean three different things because nobody said which level it was.
Because there is no notation to check, the discipline has to come from somewhere else: label every box with what it is, label every line with what it does and over what protocol, and never mix two levels on one canvas. Those three rules do most of the work that a specification would otherwise do for you.
03The word container is the problem#
C4 predates Docker's dominance and uses container in its older, general sense: a thing that has to be running for the system to work and that can be deployed on its own. A single-page application is a container. So is a database, a serverless function, a message broker and a mobile app.
Level 2 is where most of the value is, and it is the level teams skip - partly because of the name, and partly because it is the first diagram that forces a real decision about what the system actually is. The container diagram article works through one end to end.
04Using it without it going stale#
A C4 diagram set has the same failure mode as any other architecture documentation: it is accurate on the day it is drawn and quietly wrong six months later. Two things help, and neither is about drawing.
The first is to keep the levels in one model rather than in four unrelated pictures. If the API on your context diagram and the API on your container diagram are the same element, renaming it is one edit; if they are two boxes that happen to share a label, renaming it is two edits and one of them will be forgotten. That is the argument for a model behind the views, and it is the same argument keeping a model current makes at length.
The second is to draw fewer levels. A context and a container diagram that are true beat four levels where two are fiction. Level 4 in particular should be generated from the code or left out - a hand-drawn class diagram is a snapshot of an opinion, and the compiler has a more current one.
In one line each
- 01Four levels, four questions: who uses it, what are the pieces, what is inside a piece, what are the classes.
- 02C4 defines content, not notation - so draw it in UML, in ArchiMate, or in plain boxes, and be consistent.
- 03A container is anything separately deployable or runnable. It has nothing to do with Docker.
- 04Draw levels 1 and 2, add 3 where there is an argument to settle, and generate or skip 4.
05Common questions#
What does C4 stand for?
Context, Containers, Components and Code - the four levels of detail, from the whole system in its environment down to the classes inside one component. The name is the table of contents.
Is C4 a replacement for UML?
No, and it is not an alternative to it either. C4 tells you which four diagrams to draw and what belongs on each; UML gives you a notation with defined semantics. They compose: a C4 container diagram drawn in UML component notation is a legal UML diagram and a correct C4 one.
What is a container in C4?
Something that has to be running for the system to work, and that can be deployed separately - a web application, a mobile app, an API, a database, a message broker. It is not a Docker container, and the collision of names is the single most common source of confusion about the model.
Do I have to draw all four levels?
No. Most teams draw levels 1 and 2 and stop. Level 3 is worth it for a container complex enough that its internals are argued about, and level 4 is worth it almost never - the code is already the description of the code.
In this series
- 01What is C4?
- 02Container diagram
- 03C4 vs UML
Related reading
Structure diagrams
Modelling practice
Structure diagrams
Foundations
Modelling practice