Let me start by doing the exact thing this post argues against. Here is a diagram.
Yes, I’m aware of the irony: a post about how diagrams don’t tell you the important things, opening with a diagram. Bear with me, because the diagram is the exhibit, not the argument. It’s here precisely so I can point at everything it leaves out.
C4 is genuinely good — at one thing
Credit where it’s due. Simon Brown’s C4 model is the best lightweight way I know to describe software structure. Four zoom levels — system Context, Containers, Components, and (rarely) Code — give you a shared language that a developer and a stakeholder can both read, without the ceremony of a heavyweight notation. It’s a natural fit for microservices and for teams working in an agile way, because you can draw it in minutes and keep it roughly current. I reach for it constantly. This is not a takedown.
But look at what the diagram above actually says. The web application calls the API. The API reads and writes a database and calls a payment provider. Every box is accurate. Every arrow is real. And it tells you almost nothing you’d need to safely change any of it.
The questions the boxes can’t answer
Sit with the diagram for a moment and ask the obvious questions:
- Why is the API a separate container from the web application, rather than one deployable? Load? Team boundaries? A blast-radius decision? The diagram just shows two boxes.
- Which principle put the database behind the API instead of letting the web app reach it directly? There clearly is one. It isn’t written anywhere.
- Who decided to use an external payment provider rather than build it, what were they optimising for, and what did they rule out to get here?
- What quality attribute is this whole shape serving? A diagram optimised for throughput and one optimised for auditability can look identical.
- What would break if you collapsed the API back into the web app next quarter? The diagram won’t warn you, because it never recorded why they were split.
Every one of those is a why, and C4 is a notation for what. It draws structure — the nouns and the lines between them. It has no vocabulary for motivation, for the decisions that produced the structure, or for the constraints the structure is quietly honouring. That’s not a flaw in C4. It’s a category boundary, and the trouble starts when we forget the boundary is there.
This is an old lesson, badly relearned
The people who built the big enterprise-architecture frameworks worked this out decades ago, even if they buried it under too much process. Zachman’s framework is, at heart, a grid: rows for different stakeholders, and columns for what, how, where, who, when — and why. C4, mapped onto that grid, lights up one or two cells and leaves the rest dark. The “why” column — the motivation, the drivers, the rationale — is simply not something a container diagram has a place to put.
The ISO standard for architecture description (42010, if you like a reference number) makes the same point more usefully: an architecture is described through multiple viewpoints, each chosen to address specific stakeholder concerns. A structural diagram is one viewpoint serving some concerns. It was never meant to serve all of them. Treating your C4 diagrams as “the architecture” is like treating the floor plan as the building — accurate, essential, and silent on why the load-bearing wall is where it is.
The governance gap, in one sentence
Here’s why this matters beyond pedantry: when the diagram is the only artefact, the reasoning lives exclusively in people’s heads — and heads leave.
The refactor that “makes no sense” is almost always someone undoing a decision whose rationale was never captured. The endless re-litigation of a boundary is a team that agreed the what on a diagram but never wrote down the why. I’ve come round to lightweight architectural governance precisely because I kept watching this happen: the picture was pristine and the thinking behind it had evaporated.
Don’t replace C4. Complete it.
The fix is not “adopt Zachman” or draw more boxes. It’s to pair the diagram with the small set of things that carry the reasoning it can’t:
- A short set of principles — the standing rules that explain why boxes land where they do (“data is only ever reached through its owning service”, and so on). Half a page beats a folder.
- Architecture decision records for the load-bearing choices — the API/web split, the buy-not-build, the roads not taken. This is the missing “why” column, and it’s cheap.
- A note on the quality attributes the shape is serving, so the next person knows what they’d be trading away. This is the same reason there’s no such thing as the “right” architecture — only one appropriate to forces you have to actually name.
None of that is heavyweight. It’s a viewpoint or two added to serve the concerns C4 doesn’t — which is exactly what the old standards were nagging us to do all along.
So keep the diagram. It’s genuinely useful, and I’ll draw the next one happily. Just don’t mistake it for the architecture. The diagram tells you what the system is. It will never tell you what it’s for, why it’s shaped this way, or what you’d be breaking if you changed it — and those are the things the next person actually needs to inherit.