The Four C4 Levels: Context, Container, Component, Code
The genius of C4 is its four zoom levels. This guide goes deep on each one - what belongs there, who reads it, and the mistakes that blur the boundaries between them.
The C4 model's power comes from a single discipline: at any given level of zoom, every element is the same kind of thing. That sounds trivial, but it is exactly the discipline that most architecture diagrams lack, which is why they end up showing a whole system next to a single database next to one class. C4's four levels - context, container, component, and code - each define precisely what "kind of thing" you are drawing.
This guide takes each level in turn and gets concrete about what belongs there, who the audience is, and the specific mistakes that blur the levels together. If you only remember one thing, make it this: never mix levels in a single diagram. When you feel the urge to add detail, that is the signal to zoom to the next level in a new diagram, not to overload the current one. The dedicated tool at /diagram-tools/c4-diagram is built around these levels.
Level 1 - Context: the system among its neighbors
At the context level, your entire system is one box. Around it are the people who use it and the external systems it depends on or serves. Nothing internal appears. The audience is everyone: engineers, product managers, executives, sales, support. A context diagram answers "what is this system, who uses it, and what does it talk to" in a picture anyone can grasp in a minute or two.
The most common context-level mistake is leaking container detail - showing your database or your front end as separate boxes. The moment you do that, your system is no longer a single box and the diagram is trying to be a container diagram. Keep the discipline: at level one, your system is atomic. If a stakeholder needs to see inside, that is what level two is for.
Level 2 - Container: the deployable pieces
Zoom into the system box and you get the container level: the separately deployable or runnable units. A single-page app, a mobile app, an API service, a background worker, a database, a message broker - each is a container. Arrows between them are labeled with the technology and protocol of the communication. The audience is technical: engineers, architects, and technically fluent product people.
Remember that "container" here has nothing to do with Docker; it means a runnable process or datastore. The container diagram is the level most teams live in day to day, because it is detailed enough to reason about deployment, scaling, and failure while still fitting the whole system on one page. Label every container with its technology and every arrow with how communication happens - that is where the diagram earns its value.
Level 3 - Component: inside a single container
Zoom into one container and you reach the component level, which shows the major building blocks inside that container and their responsibilities - controllers, services, repositories, gateways, and how they collaborate. The audience is the engineers working in that container, and the purpose is usually onboarding or explaining a complex piece.
The honest caveat is that component diagrams go stale fastest, because internal structure changes more often than deployment topology. Draw them selectively, for the containers that are genuinely complex enough to warrant a guide, and accept that they need more frequent updates. For simple containers, a component diagram is often more maintenance burden than it is worth.
What distinguishes the levels
A quick reference for keeping the four levels straight and choosing the right one.
- Context: one box is your whole system; audience is everyone; question is "what is this and who uses it."
- Container: one box is a deployable app or datastore; audience is technical; question is "how is it built and deployed."
- Component: one box is a code module inside a container; audience is that container's developers; question is "how is this container organized."
- Code: one box is a class or interface; audience is developers in the moment; question is "how is this component implemented."
- As you descend, the audience narrows and the diagram goes stale faster.
- Each level should fit comfortably on one screen; if it does not, you are probably mixing levels.
- Zooming means a new diagram, never more detail crammed into the current one.
Level 4 - Code, and why you rarely draw it
The code level drops to individual classes and interfaces, and C4's own guidance is to almost never draw it by hand. Your IDE and automated UML generators produce this detail more accurately than you could maintain, and it changes with every refactor. Treat level four as "generate on demand if you ever need it, do not store." The judgment about what matters, which is where human diagramming adds value, has nothing left to add at this level.
In practice, the return on effort is overwhelmingly at levels one and two. A living context diagram and a living container diagram per system, kept accurate and stored where engineers work, deliver most of the value of C4. In Atlas Diagram Studio you can draft these with AI at /diagram-tools/ai-diagram-generator, refine them with the C4 shapes at /diagram-tools/c4-diagram, and import existing Mermaid or .drawio versions. For a tool comparison, /diagram-tools/vs/drawio covers the trade-offs.