C4 Architecture Model

The Problem with Most Architecture Diagrams

Most architecture diagrams are drawn once, presented in a meeting, and never updated. They sit in a Confluence page or a shared drive, slowly drifting from reality. Six months later, someone pulls one up during an incident and realizes half the services on it no longer exist and three new ones are missing.

The deeper problem is that most teams have no shared convention for what a box on a diagram actually means. One person draws a box labeled "backend" and means the entire API layer. Another person draws a box labeled "backend" and means a single microservice. In the same meeting, looking at the same diagram, two engineers are imagining completely different systems. Nobody notices until something breaks.

C4 fixes this by giving you four explicit zoom levels, each with a clear definition of what goes on it and who it is for.

The Four Levels

Level 1: Context

This is the highest zoom level. It shows your system as a single box, surrounded by the people who use it and the external systems it talks to. No internal details. No services, no databases, no queues.

The Context diagram answers one question: what does this system do and who does it interact with? If a new engineer joins and cannot understand this diagram in two minutes, it is too complicated.

This is also the diagram you show to non-technical stakeholders. Product managers, executives, compliance teams. They do not need to know you are running Kafka. They need to know that your system receives orders from the mobile app and sends shipment updates to the logistics provider.

Most teams skip this level because it feels too simple. That is exactly why it is valuable. If you cannot draw a clean Context diagram, it usually means your system boundaries are not well defined, and that is a real architectural problem hiding behind missing documentation.

Level 2: Container

Zoom in one level. Now you open up that single box from the Context diagram and show the major technical building blocks inside it. Web applications, APIs, databases, message queues, file storage. Each container is a separately deployable or runnable thing.

The Container diagram answers: what are the major technical pieces and how do they communicate? This is the diagram most useful during design reviews, capacity planning, and onboarding. A new team member should be able to look at this and understand the shape of the system within ten minutes.

Keep it focused. If your Container diagram has more than fifteen boxes, you are probably mixing levels. A Kubernetes pod is not a container in C4 terms, and neither is a shared utility library. Think in terms of things you deploy and run independently.

Level 3: Component

Zoom into a single container and show its internal structure. The major components, modules, or groupings of code inside it. This is where you show what lives inside a service and how the pieces relate to each other.

The Component diagram answers: how is this container structured internally? This is useful for the team that owns the container. It is rarely useful for anyone else. If you are showing Component diagrams to people outside the owning team, you are probably over-sharing detail.

Not every container needs a Component diagram. If a service is small and well understood by its team, skip it. The effort to keep it current is not worth the occasional reference. Reserve Component diagrams for complex services where the internals are complex enough that a diagram actually saves people time.

Level 4: Code

This is UML-level detail. Class diagrams, entity relationship diagrams, the internal structure of a single component. In practice, almost nobody maintains Level 4 diagrams by hand, and for good reason. Code changes too fast. By the time you finish the diagram, the code has moved on.

If you need Level 4 diagrams, generate them from the codebase using tooling. IDE plugins and static analysis tools can produce these on demand. Treat them as disposable, not as documentation.

When C4 Works Well

C4 works best when your system is large enough to need multiple views but not so large that the model itself becomes a project to maintain. Practically, this means organizations with five to fifty services and multiple teams.

Onboarding is where it pays off fastest. A new engineer starts with the Context diagram, zooms into the Container diagram, then dives into the Component diagram of the service they will own. That broad-to-narrow progression builds a mental model faster than reading code or sitting through hours of knowledge transfer.

It also sharpens design reviews. When someone proposes a new service or a major refactor, existing C4 diagrams give the discussion a shared frame of reference. Instead of debating what "the backend" means, everyone is looking at the same Container diagram.

During incidents, the Container diagram shows you the blast radius. Which containers talk to the failing service? What downstream systems are affected? This is information you want on a wall, not buried in someone's head.

When C4 Does Not Help

C4 is not useful for very small systems. If you have one API, one database, and a frontend, drawing four layers of diagrams is overhead with no payoff. A single architecture diagram on the README is enough.

It also does not help if nobody maintains the diagrams. Outdated C4 diagrams are worse than no diagrams because people trust them. If your team does not have a habit of updating documentation, adding a new documentation framework will not fix that. Fix the habit first.

And C4 is a structural model, not a behavioral one. It shows you what the pieces are and where they sit. It does not show you how data flows through the system during a specific request, or how the system behaves under failure conditions. For that, you need sequence diagrams, data flow diagrams, or failure mode analysis. You still need those. C4 sits alongside them, not above them.

Making It Practical

The biggest risk with C4 is treating it as a documentation project that happens once and gathers dust. To avoid that:

Someone needs to own each diagram. The Context diagram belongs to whoever is responsible for the overall system. Container diagrams belong to the teams that run those containers. If nobody owns it, nobody updates it. That is not a process problem. That is a people problem.

The easiest way to keep diagrams current is to attach updates to things people already do. Review them during quarterly planning when scope changes. Update them during design reviews when new containers show up. Revisit them after major incidents when you discover the diagram was wrong. Do not create a separate "diagram update" ritual. That will die within a quarter.

Tooling matters too. Structurizr, IcePanel, or even Mermaid diagrams checked into your repo keep diagrams close to the engineers who need to update them. Diagrams locked inside presentation decks or drawing tools behind a separate login die faster than anything else.

And start small. Draw the Context diagram and the Container diagram. That covers 80% of the value. Add Component diagrams later, only for services complex enough to justify them. Skip Level 4 unless you have tooling that generates it automatically.

The Real Value

C4 is worth adopting not because of the diagrams themselves, but because it forces your team to agree on what a box means, what level of detail belongs where, and who each diagram is for. That agreement is worth more than any individual diagram. Once everyone uses the same zoom levels and the same vocabulary, architecture discussions stop going in circles. Design reviews get to the point faster. New engineers stop guessing how the system fits together. The diagrams help, but the shared understanding behind them is what actually changes how your team works.