Boxes and Arrows
Picture this. You've just joined a new team. On your first day, you ask the question every new engineer asks: "So… how does this whole thing actually work?"
Someone digs up a diagram. It was drawn eighteen months ago by a developer who has since left the company. It's a sprawling canvas of forty-seven boxes connected by a spaghetti of crisscrossing lines. Some boxes are databases, some are microservices, some are teams, and one — inexplicably — just says "Legacy Stuff (do not touch)." The arrows have no labels. Nobody in the room can fully explain it, and everyone quietly admits it's probably out of date anyway.
If that scene feels painfully familiar, you're not alone. This is the natural end-state of almost every software architecture diagram, and it happens for a few predictable reasons.
Why traditional diagrams fall apart
The core problem is that most architecture diagrams have no rules. They're drawn ad hoc, so every diagram invents its own visual language. A box on one diagram might mean a server; on the next, a team; on the next, an abstract "concept." Because nothing is standardized, every diagram has to be decoded from scratch, and only its author truly understands it.
That lack of shared meaning creates a cascade of familiar frustrations:
- Ambiguous notation. What does this box represent — an application, a process, a physical server, a bounded context? What does that arrow mean — an API call, a data flow, a dependency, or just "these two things are vaguely related"? If a diagram can't answer these questions on its own, it isn't communicating; it's decorating.
- Mixed levels of abstraction. A single diagram tries to show the entire company's system landscape and the class structure of one particular module, all at once. It's the equivalent of a map that shows both the whole of Europe and the layout of your kitchen on the same sheet of paper. Useful to no one.
- Missing context. Diagrams often assume you already know how everything fits together — which is precisely the knowledge a newcomer is trying to acquire.
- Inconsistency across the team. Every engineer draws differently, so five diagrams of the "same" system look like five different systems.
- Instant staleness. Because these diagrams are painstakingly hand-drawn in a tool disconnected from the code, updating them is a chore everyone avoids. Within weeks, the diagram and the reality have quietly diverged.
The tragic result is that teams often stop drawing diagrams altogether. Architecture knowledge retreats into people's heads, gets lost when they leave, and has to be painfully reverse-engineered by every new hire — usually by reading the source code and guessing.
A quick reality check
None of this means diagrams are useless. It means undisciplined diagrams are useless. A good architecture diagram is one of the highest-leverage documents a team can own: it onboards new engineers in hours instead of weeks, gives everyone a shared vocabulary in design discussions, and surfaces risky dependencies before they become 2 a.m. incidents. The problem was never diagramming — it was the lack of a simple, shared set of rules.
Enter the C4 model
The C4 model is that simple, shared set of rules. Created by software architect Simon Brown, it's described as "an easy to learn, developer-friendly approach to software architecture diagramming." The whole thing is designed to be learnable in an afternoon and usable on a whiteboard, in a wiki, or generated straight from code.
Its central insight is almost embarrassingly simple: you shouldn't try to show everything on one diagram. Instead, you create a small set of diagrams at different levels of detail, and you let the reader choose how deep they want to zoom. Each diagram has one job, one level of abstraction, and one intended audience.
The "C4" name comes from the four levels of abstraction the model uses, each starting with the letter C:
- Context — How your system fits into the wider world of users and other systems.
- Containers — The high-level technical building blocks (apps, APIs, databases) that make up your system. (Note: "container" here is a general term, not specifically a Docker container — more on that later.)
- Components — The major logical pieces inside a single container.
- Code — How an individual component is implemented, down to the class level (optional, and usually skipped).
Crucially, C4 sits on top of a few clear building blocks — a person (a user), a software system, a container, and a component — so that everyone drawing and reading the diagrams shares the same vocabulary. And the model is deliberately notation- and tooling-independent: you can draw it with sticky notes, in a generic diagramming tool, or as "diagrams as code." C4 tells you what to draw and at what level; it leaves the how up to you.
The one analogy that makes it all click
If you remember one thing from this guide, make it this: the C4 model is Google Maps for your software.
When you use an online map, you don't stare at a single image showing every street on Earth at once — that would be an unreadable mess (which is exactly what our forty-seven-box diagram was). Instead, you zoom. You start with the whole country, zoom in to a region, then a city, then a single street. Each zoom level shows the right amount of detail for the question you're asking, and hides everything else.
C4 works exactly the same way. The System Context diagram is your view from space. Zoom in and you get the Container diagram — the "cities" of your system. Zoom in again for the Component diagram — the "streets." And if you really need it, zoom in one final time to the Code — the individual "buildings."
That single idea — consistent, purposeful zooming — is what turns architecture diagramming from a dreaded chore into a genuinely useful map of your system. In the next section, we'll unpack the Google Maps analogy in full and use it as the backbone for everything that follows.