The C4 model, explained by people who draw them

What the C4 model actually is

C4 is a way of describing the static structure of a software system using four nested levels of detail, created by Simon Brown. It is not a tool, a file format or a standard body — it is an agreement about abstraction. Each level answers one question for one audience, and every box on a diagram is one of four things: a person, a software system, a container, or a component.

That constraint is the whole point. Most architecture diagrams fail not because they are ugly but because a single picture mixes a business capability, a Kubernetes pod, a Java class and a third-party SaaS, all drawn as identical rectangles. C4 forbids that mixing by giving each abstraction its own level.

The four levels

Think of it as zooming a map: country, city, district, street. You do not draw all four for every system — you draw down to the level where the reader stops asking questions.

• —
  Level 1 — System Context — Your system as a single box, the people who use it, and the other systems it talks to. The diagram a non-technical stakeholder can read.
• —
  Level 2 — Container — The separately runnable or deployable things inside your system: a web app, an API, a database, a worker, a mobile app. The most useful diagram most teams never draw.
• —
  Level 3 — Component — The major building blocks inside one container, and their responsibilities. Drawn per container, only where the container is complicated enough to warrant it.
• —
  Level 4 — Code — Classes, interfaces and their relationships inside one component. Almost always better generated from the source than hand-drawn.

A "container" is not a Docker container

This is the single most common misreading of C4, and it predates Docker. In C4 a container is a separately runnable or deployable unit that executes code or stores data — an application, an API process, a database, a file system, a shell script that runs on a schedule.

A container may happen to ship as a Docker image, or ten containers may share one image, or one container may run as three replicas. Deployment is a different concern; C4 has a separate deployment diagram for it. If your Level 2 diagram is drawing pods and nodes, you have drawn infrastructure and called it architecture.

Notation: deliberately boring

C4 is notation-independent. There is no required shape language, no UML compliance, no stereotype vocabulary to learn. The convention that makes diagrams readable is simply that every element carries its name, its type, the technology it is built with, and a one-line description, and that every arrow is labelled with what actually flows and how.

An unlabelled arrow is the most expensive thing on an architecture diagram. "SPA → API" tells a reader nothing; "SPA → API: submits payment requests, JSON/HTTPS" tells them what breaks when the arrow breaks.

• —
  Every box — Name · type · technology · one line of description.
• —
  Every arrow — What it does, in which direction, over what protocol.
• —
  Every diagram — A title, a scope, and a legend if you used colour to mean something.

How to start on a system you already have

1. Name the system and its boundary in one sentence. If you cannot, the boundary is the problem, not the diagram.
2. Draw the System Context: users, the system, everything external it depends on. Twenty minutes, on a whiteboard, out loud with two colleagues.
3. Draw the Container diagram from deployment reality — what is actually running in production, not what the wiki says.
4. Stop. Ship those two. They already cover most of what a new joiner or an incident responder needs.
5. Add a Component diagram only for the one or two containers people repeatedly get lost in.
6. Attach the prose. A diagram that cannot say why a decision was made is a picture, not documentation.

The hard part is not drawing them

Every team can produce a good C4 set in an afternoon. The failure mode arrives six months later, when the diagram is in a slide deck, the reasoning is in a wiki nobody edits, the sequence diagrams are in a third tool, and the API contract is in a fourth. Nothing is wrong individually; collectively, no one trusts any of it.

The fix is structural, not motivational: keep the explanation attached to the element it explains, so that opening the box opens the documentation. That is the idea Viaduct is built around — the model is the index for everything else the team knows about the system.