Introduction to the C4 Model for Software Architecture
I still remember the whiteboard session that made me rethink everything about architecture diagrams. We were onboarding a new developer, and I spent 45 minutes drawing boxes and arrows trying to explain our e-commerce platform. By the end, she looked more confused than when we started. The diagram had everything — microservices, databases, message queues, external APIs — all crammed together with inconsistent notation and no clear hierarchy.
That evening, I stumbled upon Simon Brown's C4 model, and it was one of those "why didn't I think of this?" moments. The idea is deceptively simple: instead of cramming everything into one diagram, you create multiple diagrams at different zoom levels. Like Google Maps, you start zoomed out to see the big picture, then zoom in progressively to see more detail.
The Four Levels of C4
The "C4" stands for four levels of abstraction, each answering different questions:
Level 1: System Context
This is the 30,000-foot view. Your entire system is a single box, and you show:
- Who uses your system (people or roles)
- What external systems you integrate with
That's it. No internal details, no technology choices, no databases. Just "here's our system, here's who uses it, and here's what it talks to."
When I first drew a System Context diagram for our platform, it fit on a single slide. Our CEO could understand it. That had never happened before with my architecture diagrams.
Here's what makes this level powerful: it forces you to think about boundaries. What's inside your system versus what's outside? What do you own versus what you depend on? These questions seem obvious, but I've seen teams struggle to answer them clearly.
Level 2: Container Diagram
Now we zoom in one level. A "container" in C4 terminology isn't a Docker container — it's any deployable unit that runs code or stores data:
- Web applications
- Mobile apps
- Backend services
- Databases
- Message queues
- File storage
This diagram shows the high-level technical architecture. You can see the major technology choices (React frontend, Go backend, PostgreSQL database) and how data flows between them.
I find this level most useful for:
- Planning infrastructure and deployments
- Discussing technology choices with the team
- Explaining the system to new backend or frontend developers
One thing I learned: be careful about granularity here. If you have 30 microservices, don't show all 30 as separate containers. Group related services or create multiple Container diagrams for different areas of your system.
Level 3: Component Diagram
This is where we zoom into a single container. Components are the major structural building blocks inside that container — think services, repositories, controllers, or modules.
For our Go backend, a Component diagram might show:
- HTTP handlers
- Business logic services
- Repository interfaces
- External API clients
I'll be honest: I don't create Component diagrams for every container. Only the complex ones that new developers struggle to understand. For a simple CRUD service, the code itself is the documentation.
Level 4: Code Diagram
The deepest level shows actual code elements — classes, interfaces, functions. Simon Brown himself says this level is optional and often auto-generated from code.
In practice, I rarely create Code diagrams manually. When I do, it's for particularly complex algorithms or patterns that benefit from visual explanation. Most of the time, if you need this level of detail, you should be reading the actual code.
Why C4 Clicked for Our Team
Before C4, our architecture documentation was a mess. We had:
- Visio diagrams from 2019 that nobody updated
- Whiteboard photos in random Slack channels
- README files with ASCII art that sort of explained things
- Tribal knowledge that walked out the door when people left
The C4 model gave us a framework that actually works. Here's why:
It's simple enough to remember
Four levels. That's it. No need to memorize 14 different UML diagram types or argue about whether something should be a "component" or a "module" in the UML sense.
Different audiences, different diagrams
Our CEO looks at the System Context diagram. Our architects discuss the Container diagram. Our developers work with Component diagrams. Everyone gets the right level of detail for their needs.
It stays current
Because C4 diagrams are relatively simple, they're not painful to update. When we add a new external integration, updating the System Context diagram takes 5 minutes. Compare that to updating a detailed UML diagram with every class and method.
It's tool-agnostic
We started with draw.io, moved to Miro for collaboration, and now use Archyl for AI-assisted diagramming. The C4 model works with any tool because it's about the concepts, not the notation.
Common Mistakes I've Made (So You Don't Have To)
Mistake 1: Showing too much detail too early
My first Container diagram had 47 boxes. It was accurate but useless. Now I follow a rule: if your diagram doesn't fit on one screen, you're at the wrong zoom level.
Mistake 2: Forgetting the relationships
A diagram with boxes but no arrows is just an inventory. The relationships — who calls whom, what data flows where — are often more important than the boxes themselves. Label your arrows. Describe the protocols and data formats.
Mistake 3: Not updating after changes
The best diagram is useless if it describes the system from two years ago. We solved this by making diagram updates part of our PR checklist for architectural changes. It's not perfect, but it helps.
Mistake 4: Over-engineering the notation
I spent a week designing custom icons and color schemes for our C4 diagrams. Total waste of time. Simple boxes with clear labels work fine. Focus on content, not aesthetics.
Getting Started
If you're new to C4, here's what I'd suggest:
Start with System Context. Take 30 minutes to draw your system as a single box, surrounded by the users and external systems. This alone provides value.
Add one Container diagram. Pick your most complex system and break it down into deployable units. Show how they communicate.
Stop there for now. Don't try to document everything at once. Let the diagrams prove their value before investing more time.
Make it collaborative. Share the diagrams with your team. Get feedback. Architecture documentation shouldn't be a solo activity.
How We Use C4 at Archyl
Building Archyl, we obviously eat our own dog food. Our architecture documentation uses C4 throughout:
- The System Context diagram shows Archyl connecting to various git providers, AI services, and payment systems
- Container diagrams break down the Go backend and React frontend
- Component diagrams detail the discovery service and diagram rendering engine
What's powerful is linking these diagrams to other documentation. An Architecture Decision Record about choosing PostgreSQL over MongoDB links directly to the database container in our Container diagram. User flows reference the specific components they traverse.
This interconnected documentation is what we're building into Archyl — the ability to see your architecture not as isolated diagrams but as a connected knowledge graph.
Conclusion
The C4 model isn't revolutionary in its concepts. Levels of abstraction and hierarchical decomposition have been around forever. What Simon Brown did brilliantly was package these ideas into a simple, memorable framework that actually gets used.
If your architecture documentation is a mess of outdated Visio files and whiteboard photos, give C4 a try. Start small, with just a System Context diagram. You might be surprised how much clarity a single, well-thought-out diagram can bring.
This is part of our series on architecture documentation. Next up: How AI can automatically discover your architecture and Why documentation matters more than you think.