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.
What counts as a container
A container is a separately runnable or deployable unit that executes code or stores data. Server-side web applications, single-page applications, mobile apps, desktop apps, API processes, serverless functions, databases, blob stores, message brokers, scheduled jobs, shell scripts — all containers.
The test is independence: can it be started, stopped, scaled or replaced without taking the rest of the system with it? If yes, it is a container. If it only exists inside another process, it is a component.
Not a Docker container
C4 used the word first. Packaging and deployment topology belong on a deployment diagram; Level 2 is about the logical runtime pieces and what they are written in.
What goes on it
- Each container — Name, the technology it runs on, and one line saying what it is responsible for.
- Data stores — Databases and caches as containers, labelled with the engine — not a generic "DB" cylinder.
- Protocols on every arrow — JSON/HTTPS, gRPC, AMQP, JDBC — the reader needs to know what the coupling actually is.
- The people and external systems — Carried forward from Level 1 so the diagram stands on its own.
A worked example
Seven boxes, every arrow labelled with a protocol, every box labelled with a technology. A new engineer can read this and know where to put a breakpoint.
Draw it from production, not from intent
Build the Container diagram from what is deployed: the service list, the pipeline definitions, the things that page someone at 3am. Aspirational containers — the service that is "about to be extracted" — are how a diagram starts lying.
If a container exists in production but nobody wants to draw it, that is a finding. The awkward cron job that reconciles two databases is exactly the box the next incident will be about.
Failure modes
- Infrastructure creep — Load balancers, ingresses, VPCs and nodes. Real, but a deployment concern.
- One box per repository — Repositories are a source-control choice; containers are a runtime one.
- Missing the data stores — A diagram without databases hides the coupling that is hardest to change.
- Sixty containers, no grouping — At that size, split by bounded context and give each its own Level 2.
Frequently asked
Is a Docker container the same as a C4 container?
No. A C4 container is a logical runtime unit — an app, an API, a database. It may be packaged as a Docker image, several images, or none at all. Deployment topology belongs on a C4 deployment diagram.
Are serverless functions containers?
Yes. A Lambda function is independently deployable and executes code, so it is a container. If you have two hundred of them, group them by the capability they serve rather than drawing each one.
Should a message broker be a container?
Yes, if you run it as part of your system. It stores data, it can fail on its own, and the arrows into and out of it describe real coupling.
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.