Good architecture is more than just good code—it’s clear communication. The C4 Model: Visualizing Software Architecture is a practical guide to creating diagrams that help teams understand, build, and talk about software systems more effectively
As AI Consultant, I can say for sure that while coding is taken over by AI agents, the architects must have super clarity on the systems that they are building and importance of communication will be even more – Vikas Jain
Resources
The C4 Model: How to Draw Software Architecture People Actually Understand
Every team I have worked with has the same whiteboard photo sitting in a Slack channel somewhere. Twelve boxes. Some arrows. A cloud shape that nobody can explain. Someone wrote “auth?” next to a line and then left the company.
That photo was useful for about forty minutes. After that it became a puzzle.
This is the problem Simon Brown set out to fix with the C4 model, and it is the subject of his new book, The C4 Model: Visualizing Software Architecture (O’Reilly, June 2026). The book opens with a line I keep coming back to: good architecture is more than just good code, it’s clear communication.
I want to walk through what the C4 model is, how the four levels work, and what actually changes on a team that adopts it. No theory dumps. Just the parts you can use.
What is the C4 model?
The C4 model is a way of drawing software architecture using four levels of zoom: Context, Container, Component, and Code. Each level shows a different amount of detail for a different audience. It was created by Simon Brown and it is deliberately notation independent and tooling independent, so you can draw it on a napkin or generate it from code.
The core idea is a map analogy. Think about how you use Google Maps. You start zoomed out at country level, then you zoom into the city, then the street, then the building. Nobody complains that the country view is missing street names, because everybody understands what zoom level they are looking at.
Architecture diagrams usually fail because they mix zoom levels. One box is a whole third-party company. The box next to it is a Java class. Both are the same size and the same colour. That is why nobody can read your diagram.
Why “boxes and lines” stops working
Most teams have quietly given up on UML. Fair enough, it was heavy. But we replaced it with nothing. We kept the boxes and dropped the shared meaning.
So you end up with diagrams where:
- Nobody knows if a box is a system, an app, a service, or a class.
- An arrow could mean “sends data to”, “depends on”, “deploys to”, or “we’re not sure”.
- There is no key, so every reader invents their own.
- The diagram is six months old and there is no way to tell.
The C4 model does not solve this with more rules. It solves it with a small set of shared words. If everyone on the team agrees on what “container” means, half the confusion disappears before anybody opens a drawing tool.
The four levels, explained simply
Level 1: System Context diagram
This is the widest view. One box in the middle for your software system, and around it the people who use it and the other systems it talks to.
No technology. No databases. No internal detail.
The audience here includes people who do not write code: product managers, business stakeholders, a new director who joined last week. The question this diagram answers is simple. What is this thing, who uses it, and what does it connect to?
If you only ever draw one diagram, draw this one. It takes twenty minutes and it saves hours of meetings.
Level 2: Container diagram
Now you zoom into your system and show the separately runnable or deployable pieces inside it. A container in C4 terms is an application or a data store. A Spring Boot service. A React single-page app. A mobile app. A Postgres database. An S3 bucket. A message broker.
Important: this has nothing to do with Docker. Simon Brown was using the word before Docker existed, and it trips people up constantly. If it helps your team, call them “deployable units” out loud and keep “container” only in the diagram.
This is the diagram developers actually want. It shows the shape of the system, the technology choices, and how the pieces talk to each other. Label the protocols. “Sends order events to, via Kafka” is useful. A bare arrow is not.
For most teams, Context plus Container is enough. The official guidance says exactly that: you do not need all four levels, only the ones that add value.
Level 3: Component diagram
Zoom into one container and show the major building blocks inside it. A component is a grouping of related functionality behind a well-defined interface. Not a class. Not a file. Something like “Payment Reconciliation Service” or “Order Validator”.
I would draw this for maybe one or two containers in a system, usually the ones that are complicated or that people keep arguing about. Drawing it for every container is a fast way to create work nobody maintains.
Level 4: Code diagram
A class diagram, an ER diagram, something at implementation level.
Honestly? Draw this rarely, and when you do, generate it from the code rather than hand-drawing it. Hand-maintained code diagrams go stale within a sprint. Your IDE can produce one on demand and it will always be correct.
Three extra diagrams worth knowing
Beyond the four levels, the model gives you three supplementary diagrams. These are the ones I reach for most often in real work.
System Landscape. The view above Context. All the systems in your organisation or department and how they relate. Useful when someone asks “what do we even own?”
Dynamic diagram. Shows how elements collaborate to handle one specific scenario, with numbered steps. This is the one to draw when you are debugging a flow, explaining a race condition, or onboarding someone into a gnarly checkout process.
Deployment diagram. Maps your containers onto actual infrastructure: regions, clusters, nodes, environments. Your platform and security people will thank you.
Notation: the handful of rules that matter
The C4 model does not force a notation on you. There is no official blue and grey. But it does ask for a few things, and these are the ones that make the difference between a diagram that works alone and one that needs a presenter standing next to it.
- Give every diagram a title that says what type it is and what it covers.
- Add a key or legend. Explain every shape, colour, line style, and arrow head you used. If you cannot explain a colour, remove it.
- Say what each element is. Person, Software System, Container, or Component. Write it on the box.
- Add a one-line description to each box. Enough for someone to get the responsibility at a glance.
- Label the technology for containers and components.
- Label every line, and make the label match the direction and the intent. “Reads customer records from” beats “uses”.
- Expand your acronyms or put them in the key. Your internal three-letter names mean nothing to a new joiner.
Also, think about people who print in black and white and people who are colour blind. Colour should be a bonus signal, never the only one.
How to start this week
Here is the smallest useful version of adoption, and it is genuinely small.
- Pick one system your team owns. Preferably the one people ask about most.
- Draw the System Context diagram. Twenty minutes, whiteboard is fine.
- Show it to someone who does not work on that system. Watch where they get confused. Fix those bits.
- Draw the Container diagram. Include technology labels and protocols.
- Put both in your repo, next to the code, in a text-based format so they show up in pull requests.
That last step is the one that makes it stick. Diagrams that live in a slide deck die. Diagrams that live in the repo get updated with the code, because someone reviewing a PR will notice they are wrong.
Mistakes I see most often
Treating the container diagram like a Docker diagram. Already covered, but it is the number one confusion, so it earns a second mention.
Mixing zoom levels. A box for “Salesforce” sitting next to a box for “UserRepository”. Pick a level and stay there.
Drawing all four levels on day one. You will burn a week and abandon it by month two. Start with two.
Unlabelled arrows. An arrow with no words is a question mark that looks like an answer.
One giant diagram of everything. If you need a 4K monitor to read it, it is not a diagram, it is wallpaper. Split it.
Nobody owns it. Decide who updates the diagrams and when. Usually the answer is “whoever changes the architecture, in the same PR”.
Tools that work well with C4
You do not need special software. That said, a few options are worth a look:
- Structurizr is Simon Brown’s own tool. Its DSL lets you define the model once in text and render every level from it, which means the diagrams cannot drift out of sync with each other.
- C4-PlantUML gives you C4 shapes in PlantUML. Good if your team already uses it.
- Mermaid has C4 diagram support and renders natively in GitHub markdown, which is very convenient.
- IcePanel is a hosted option with a nicer interface, aimed at bigger organisations.
- draw.io, Excalidraw, or an actual whiteboard are completely valid. The model is the point, not the tool.
My preference is text-based, because it diffs and it reviews. But a hand-drawn Context diagram that is correct beats a beautiful generated one that nobody trusts.
Is the book worth reading?
If you have read Simon Brown’s earlier free book on Leanpub or watched one of his conference talks, you already know the shape of the model. The O’Reilly edition is tighter and more practical. It runs about 180 pages across twelve chapters, roughly one per diagram type, plus chapters on notation, going beyond the basics, and putting C4 into practice.
The bit I found most useful is the Diagram Review Checklist in the appendix. It turns “this diagram feels off” into a list of specific things to check, which is exactly what you want when you are reviewing someone else’s work and trying not to sound vague.
It is a short read. You could finish it on a long flight and start applying it the next morning.
The real reason this matters
The C4 model is not a modelling revolution. It is a shared vocabulary and four levels of zoom. That is genuinely all it is.
But shared vocabulary is undervalued. When a new engineer joins and someone can hand them two diagrams that answer “what is this and what is inside it”, you have saved that person a fortnight of guessing. When a security review starts from a deployment diagram instead of a conversation, you find real gaps instead of imaginary ones.
Draw the context diagram. See how far it gets you. That is the whole recommendation.
Frequently asked questions
What does C4 stand for?
Context, Container, Component, and Code. These are the four levels of abstraction in the model, from the widest view to the most detailed.
Do I need to draw all four C4 diagrams?
No. The official guidance is to use only the levels that add value. For most teams, the System Context and Container diagrams are enough.
Is a C4 container the same as a Docker container?
No. In C4, a container means a separately runnable or deployable unit such as an application or a data store. It predates Docker and has nothing to do with it.
Is the C4 model a replacement for UML?
Not exactly. C4 defines a set of abstractions and levels of zoom, but it does not define a notation. You can express C4 diagrams using UML, plain boxes and lines, or any tool you like.
What is the difference between a container and a component in C4?
A container is separately deployable and runs on its own, like a web app or a database. A component lives inside a container and is not separately deployable, like a grouping of classes behind an interface.
Which tools support the C4 model?
Structurizr, C4-PlantUML, Mermaid, IcePanel, draw.io, and Excalidraw are all commonly used. The model itself is tooling independent.
How often should C4 diagrams be updated?
Whenever the architecture changes. Keeping them in the repository as text, so they appear in code reviews, is the most reliable way to stop them going stale.
