C4 Model: Visualizing Software Architecture

Hi everyone 👋, I'm Hung Anh.

At some point in your career, you will run into C4 diagrams inside a Software Architecture Document (SAD) written by a Solution Architect. But do you really understand what each of those diagrams means, and when to use which? And if you were asked to draw the architecture of a system today, could you?

In this article, let's break down the C4 model — the most widely used standard for architecture diagrams — so that next time you can not only read those diagrams, but draw them yourself.

Let's get started.

1. The Problem With Non-Standard Diagrams

Here is a diagram you have probably seen a hundred times:

Three problems stand out:

• Mixed abstraction levels. "Users" (people), "OrderServiceImpl" (a Java class), and "K8s cluster" (infrastructure) sit in one picture as if they were the same kind of thing.
• Made-up notation. Does the arrow from "API" to "Auth" mean calls, depends on, or deploys to? Why is one box a cloud and another a cylinder? There is no legend, so every reader guesses.
• One diagram for every audience. A CTO, a new developer, and an SRE need very different levels of detail. One diagram cannot serve all of them — so it ends up serving none.

2. The C4 Model

The C4 model, created by Simon Brown, fixes this with an idea you already use every day: zoom levels on a map. Google Maps shows the same territory as a country, a city, or a single street — each zoom level hides the details that don't matter at that height.

C4 defines four zoom levels for a software system: Context, Containers, Components, Code. And one principle behind them: agree on the abstractions first, argue about notation later.

2.1. Core Abstractions

A software system is made up of containers; each container contains components; components are implemented by code.

• Person — a human user: customer, admin, operator.
• Software System — the highest level: something that delivers value to its users. Your system is one; the payment gateway you call is another.
• Container — a separately deployable unit: a backend API, a SPA, a mobile app, a database. If it needs its own process or its own deployment, it's a container.
• Component — a group of related functionality inside a container: a service, a controller, a repository. Components are not deployable on their own — they live inside their container's process.

2.2. The Levels of the C4 Model

Running example: Shortly, a URL shortener. Users create short links, visitors click them and get redirected to the original URL, and sign-in goes through an external identity provider.

2.2.1. Level 1: System Context

Level 1 describes: what the system is, who uses it, and what it talks to.

No database, no cache, no internals — the whole system is one box. This is the diagram everyone can read, including non-technical people, and the one that changes least. Whatever system you build, draw this one first.

2.2.2. Level 2: Container

Level 2 describes: the big technical blocks and how they communicate.

A web dashboard, a Spring Boot API, PostgreSQL, and Redis. The cache earns its place because a URL shortener is extremely read-heavy — roughly 100 redirects for every link created — so most redirects should never touch the database. Every container is annotated with its technology; every arrow has a verb and a protocol.

For most systems, Context + Container is all the architecture documentation you need. If you run dozens of microservices, don't force them into one giant picture — draw one diagram per service with its direct neighbors.

2.2.3. Level 3: Component

Level 3 describes: what is inside one container.

Creating a link goes through the Link Controller; a click on a short link hits the Redirect Controller. Both delegate to a Shortener Service that generates Base62 codes, backed by a repository and the cache. If you've built a Spring Boot app, this maps naturally to your top-level packages.

Only draw component diagrams where they add real value: they change more often than the levels above, so they go stale the fastest. Many teams skip them or generate them from code.

2.2.4. Level 4: Code

Class diagrams of individual components. Don't draw these by hand — your IDE can generate them on demand, and at this zoom level the code itself is the source of truth.

C4 also defines three supplementary diagrams: System Landscape (all systems in your organization), Dynamic (how elements collaborate at runtime, with numbered steps), and Deployment (which containers run on which infrastructure).

2.3. Recap

The pattern: the deeper the zoom, the narrower the audience and the faster the diagram rots. That's why you rarely need all four levels.

2.4. Rules and Common Mistakes to Avoid

C4 doesn't dictate shapes or colors, but every good diagram follows the same rules:

1. A title: diagram type + scope ("Container diagram for Shortly").
2. A legend — every shape, color, and line style means something.
3. Every element carries its type and a short description of its responsibility.
4. Technology choices written down: [Java, Spring Boot], [PostgreSQL].
5. Every arrow is one-way and labeled with a specific verb plus the protocol. Avoid the word "uses".

Here are a few common mistakes when drawing C4 diagrams:

• Inventing levels that don't exist in the model ("sub-components", "sub-containers").
• Drawing the internals of systems you don't own.
• Mixing several zoom levels in one picture — e.g. a class next to a container, or a database table next to a software system.
• Cramming too many elements into one picture.

One thing to keep in mind: C4 describes static structure only — for workflows or data models you still need sequence or ER diagrams. And for a small team with a single service, a Context diagram plus a good README may be enough. C4 shows its value when many people need to share the same picture of the system.

3. Summary

• C4 = four zoom levels: Context, Containers, Components, Code — each answering one question for one audience.
• A C4 container is anything separately deployable — not a Docker container.
• Context + Container is the sweet spot. Draw Components only where they pay off; let the IDE generate Code diagrams.
• Every diagram needs a title, a legend, typed elements, technologies, and labeled one-way arrows.

Next time someone asks you to "draw the architecture", ask back: at which zoom level, and for whom?

See you in the next one. Happy reading! 🍵

References

1. The C4 model for visualising software architecture
2. The C4 Model for Software Architecture — Simon Brown, InfoQ
3. The C4 Model – Misconceptions, Misuses & Mistakes — Simon Brown, GOTO 2024
4. Structurizr DSL documentation
5. C4-PlantUML
6. What is the C4 model? — IcePanel
7. Design a URL Shortener — AlgoMaster