The pitch is seductive. A simple, four-level hierarchy for diagramming software architecture that promises to finally bridge the chasm between the C-suite whiteboard and your IDE. Simon Brown’s C4 model has become the de facto standard for teams tired of UML’s bloat and whiteboard chaos. It’s clean. It’s hierarchical. It solves a real, painful problem: nobody understands the damn architecture.
But a few years into its widespread adoption, the honeymoon phase is over for a vocal minority. Developers aren’t just asking “How?” anymore. They’re asking “Why?” and “At what cost?”
Let’s cut through the marketing. The C4 model is a fantastic tool in the right hands. But right now, it’s being treated as a universal solvent for communication problems that are fundamentally human, not notational. Here’s where it shines, where it burns, and what you should actually do about it.
The Core Promise: From Whiteboard Scribbles to a Shared Language
Before we wade into the mud, let’s give credit where it’s due. The C4 model addresses a catastrophic failure in software: the inability to explain what the hell the system actually does.
“Good architecture is more than just good code, it’s clear communication.”
, The C4 Model: Visualizing Software Architecture
The model’s genius is its zooming lens. Level 1 (System Context) gives you the big picture. Level 2 (Containers) shows the high-level applications and data stores. Level 3 (Components) drills into the internals. Level 4 (Code) gets you into the nitty-gritty.
It explicitly positions itself as the middle ground. The ArchiLab documentation nails the rationale:
“The C4 model is intended as a ‘middle ground’ between completely informal sketches (where important context information is easily lost over time) and highly formalized notations like UML (where such information is also lost, but for completely different reasons).”
This is a genuine insight. UML was a systems engineering dream that died on the operating table of developer indifference. C4 was designed to be learned in 15 minutes and used on a whiteboard. It removes the cognitive load of memorizing 47 different arrow types and replaces it with a hierarchy of boxes.
Where It Works: The Obvious Wins
For new projects and stable, well-understood domains, C4 is a godsend.
- Onboarding: A Level 1 and Level 2 diagram cuts the time to understand “what does this system do?” from weeks to hours. A new developer can map a user’s journey through the “container” diagram without reading 20,000 lines of code.
- Cross-Team Communication: When two teams need to integrate, a C4 diagram becomes a contract. “My Container A talks to your Container B via this API.” It’s a shared, visual language that prevents “my microservice is your monolith” arguments.
- Stakeholder Presentations: You can show a Level 1 Context diagram to your VP of Marketing, and they will actually understand it. This is a monumental win over a jumble of boxes with unlabeled tech names.
The book covers this exhaustively, walking through each diagram’s intent, audience, and usage notes. For example, the System Context Diagram answers crucial questions:
- What is the software system that we are building?
- Who is using it, and what are they doing?
- How does it fit in with the existing environment?
These are not trivial questions. If your team cannot answer them, you have a problem that no codebase can fix.
The Cracks in the Facade: Where the Model Breaks
This is where the “spiciness” comes in. A 6.0/10 spiciness score is about right. It’s not a dumpster fire, but the backlash is real and revealing.
The “Model-Code Gap” is a Chasm
The biggest unspoken tension in the C4 model is the model-code gap. The book touches on it, but practitioners live it.
The Level 3 (Component) diagram is supposed to show the major structural building blocks of a container. But what is a component? In a Spring Boot app, is it a @Service? A @Repository? A package? A module?
In my experience, and in the chatter on developer forums, the answer is “it depends.” And “it depends” is the death knell of a universal standard. The Level 3 diagram, which is supposed to be the bridge between high-level architecture and low-level code, often becomes the most inconsistent and quickly outdated diagram in the stack.
The internal C4 Model’s Blind Spot article gets to the heart of this: static diagrams are terrible at capturing the dynamic, messy reality of distributed systems. A C4 diagram shows you the happy path. It does not show you the circuit breaker opening, the retry storm, or the database connection pool exhaustion.
The “Proprietary Domain Language” Problem
One developer on a Reddit thread vented: “Tried it a few years back. Can’t remember the details but between proprietary domain language and some convoluted licences, I just decided it wasn’t worth it.”
This is a real friction point. While the C4 model itself is freely available, the tooling ecosystem around it (Structurizr, for example) has a learning curve and, for some more advanced features, a commercial license. For a team that just wants to draw a few boxes and arrows, the overhead of learning “C4-speak” and a new tool feels like unnecessary bureaucracy.
The sentiment is clear: “I just want to draw a picture. Why do I need to learn a whole new vocabulary for a box?”
The Silver Bullet Fallacy
The most dangerous aspect of the C4 model’s success is the belief that it solves the problem. It doesn’t. It’s a notation, not a design principle. Creating a beautiful C4 diagram does not mean you have good architecture. It means you have a good diagram.
You can have a beautifully documented, perfectly layered C4 model for a system that is a tangled, unmaintainable mess of technical debt. The diagram provides the illusion of understanding. The code provides the reality of a disaster.
Practical Triage: When to Use C4 (and When to Throw it Away)
Based on the research and the lived experience of teams I’ve worked with, here is a brutally pragmatic guide:
DO use C4 when:
– You are building a new greenfield system.
– Your team has 10+ people and cross-team communication is breaking down.
– You need to onboard new engineers rapidly.
– You are presenting architecture to non-technical leadership.
SKIP C4 Level 3 and 4 when:
– Your system is a tangled monolith with no clear module boundaries. A C4 diagram will just make the mess look neat.
– Your architecture changes faster than you can update the diagrams. (Hint: In most startups, this is every sprint.)
– You don’t have a tool that auto-generates diagrams from code. If you are manually drawing Level 3/4 diagrams, they will be out of date within two weeks.
The most practical advice from the book? Simon Brown himself suggests that often only Levels 1 and 2 are truly needed. The ArchiLab courses echo this: “often only level 1 and 2 of the C4 model are used.”
The Real Win: Diagrams Provide Feedback
The most valuable sentence in the entire book is not about notation. It’s about process:
“Diagrams Provide Feedback”
The best use of a C4 diagram is not as a finished artifact. It’s as a tool for conversation. Draw the Level 1 diagram on a whiteboard. Ask your team: “Is this right?” The argument that follows is infinitely more valuable than the perfectly formatted PDF you produce after two weeks of solitary work.
The Verdict: A Tool, Not a Religion
The C4 model is an excellent communication tool that has been elevated to a religion by some consulting firms and tool vendors. That’s the problem.
It solves the real problem of notation anarchy, where every developer draws their own version of a box-and-arrow diagram that nobody else understands. But it does not solve the problem of organizational dysfunction, technical debt, or poor engineering decisions.
If you’re using it to drive clarity, for onboarding, and for cross-team alignment, you’re using it right. If you’re using it to gatekeep architecture decisions, to generate reams of documentation nobody will read, or to enforce a top-down control structure, you are doing it wrong.
The most honest advice comes from a developer who simply said: “I hated it so much. I hope to never have to use it again.”
That’s not an indictment of the model. It’s an indictment of how it was applied. The tool is fine. The gatekeeping is not.
Your Next Step
Pick one system you manage right now. Draw a Level 1 and Level 2 C4 diagram on a whiteboard in 15 minutes. Show it to your team and ask “What’s wrong with this?” The conversation that follows will be more valuable than any “correct” diagram you can produce. Use the C4 model as a starting point for discussion, not a final deliverable.
And if someone demands a “complete” Level 3 and Level 4 diagram? Ask them why. If they can’t give you a better reason than “because that’s the standard”, you have permission to ignore them.
