The C4 Model Explained: Levels, Diagrams and a Worked Example

The C4 model is a way to describe software architecture at four zoom levels: system context, containers, components and code. It was created by Simon Brown, and each level is a separate diagram that answers a different question for a different audience. This guide covers what each C4 diagram shows, the notation rules, a worked example on a real open-source system, and how to produce the diagrams from code.

What are the four levels of the C4 model?

The four C4 levels are abstractions you zoom through: a software system contains containers, a container contains components, and a component is made of code. The diagrams follow the same nesting, so each one zooms into one box of the diagram above it. c4model.com, the official site, states that you do not need all four, and that system context and container diagrams are enough for most teams.

Level 1, system context. The system context diagram has a scope of a single software system and shows it in the middle with the people and other systems around it. c4model.com gives its audience as "everybody, both technical and non-technical people, inside and outside the software development team". There is no technology on this diagram. If it needs a legend explaining a protocol, it is showing too much.

Level 2, container. A container, in c4model.com's words, is "a runtime boundary around some code that is being executed or some data that is being stored": a server-side web app, a single-page app in the browser, a mobile app, a serverless function, a database, a blob store, a shell script. It is not a Docker container. The name was chosen to avoid implying anything about how the thing is deployed, and one Tomcat runtime can host several containers. The container diagram shows these units, the technology of each, and the protocol on each line between them.

Level 3, component. A component is "a grouping of related functionality encapsulated behind a well-defined interface", per c4model.com/abstractions/component. Components are not separately deployable; everything in one container shares a process space. A component diagram zooms into a single container, and is the level where developers on that container do their planning.

Level 4, code. The code level is a class diagram, entity-relationship diagram or similar for one component. c4model.com treats it as optional. In practice IDEs and generators can produce it on demand, and a hand-drawn one is out of date within a sprint.

What are the supplementary C4 diagrams?

Three supporting diagram types sit beside the four levels, and they cover things the static hierarchy cannot. c4model.com lists them as system landscape, dynamic and deployment.

The landscape diagram is level 1 with no single system in focus, which suits a platform team that owns many. The dynamic diagram is how you show "what happens when a user resets a password" without redrawing the container diagram. The deployment diagram is where Docker, Kubernetes and cloud regions finally appear.

What notation does the C4 model use?

The C4 model is notation independent: it does not prescribe boxes of a certain colour or shape. It does prescribe that a diagram stand on its own without a narrator. The notation page asks for these things:

• A title that states the diagram type and scope, such as "Container diagram for Internet Banking System".
• A key or legend for shapes, colours, line styles and arrowheads, and definitions for acronyms.
• Each element labelled with its type (person, software system, container, component), a short description of its responsibility, and a technology on every container and component.
• Each line a one-way relationship, labelled in a way that matches the direction. "Uses" is called out as too vague. Lines between containers name the technology or protocol.

Colour is left to you, with the advice to stay consistent and to check greyscale printing and colour-blind readability. Most "bad C4 diagram" complaints are one of two things: unlabelled lines, or boxes with a name and no technology.

C4 model example: a full-stack web app at three levels

To make the levels concrete, here is the full-stack-fastapi-template repository (a FastAPI backend and a React frontend with Postgres behind it), drawn at levels 1 to 3. The facts come from a repowise index of commit f4bcfab (26 October 2026). The container and component facts below are what the code shows; the names of the databases and the protocols are the human-added parts.

Level 1. The system is the template's web application. One person uses it (an API client or a signed-in user), and it depends on external systems that show up as imports in its manifests: PostgreSQL (the README names it; the code reaches it through SQLModel and Alembic), SMTP email, Sentry, and npm libraries such as the Radix UI components, Zod and Axios. The generated model found 41 external systems, almost all libraries. A good level 1 diagram promotes only the ones a stakeholder cares about (the database, the mail server) and drops the rest.

Level 2. The generated model has four containers, taken from package manifests:

The root package is tooling, so you would hide it or fold it away. The backend and frontend are the two containers a reader expects, and the container diagram's job is to draw the line between them and name the protocol, here HTTPS with JSON, which comes from the OpenAPI client the frontend is generated with. No import connects the two directly, so that line comes from a person. That is the right split: code gives you the boxes and their dependencies, people supply the protocols.

Level 3. Zooming into the backend, repowise export --format structurizr --components adds one component box per directory. In backend/app those directories are api (routes and dependencies), core (config, database and security), alembic (migrations) and email-templates. This is the diagram a developer opening the repo for the first time wants, and it is also the one where "what counts as a component" is a judgement call. Directories are a good first answer.

How do you create C4 diagrams?

There are two jobs, modelling and drawing, and c4model.com recommends separating them. Its tooling page says a modelling tool builds a non-visual model of the architecture and creates views from it, which avoids the problems of diagramming tools: no validation, no queries, copy-paste reuse and formats that are hard to diff.

For a feature-by-feature comparison of the three text notations, read Structurizr vs Mermaid vs PlantUML for C4. This page stops at the model itself.

How do you generate C4 diagrams from code?

You can generate the container and component levels from a repository, because both leave evidence in the code: manifests mark containers, and directories and imports outline components. Levels 1 and 3 are partly inferable. Protocols and deployment are not. The longer treatment is in generate C4 diagrams from code.

repowise does this from the index it already builds. repowise export --format structurizr writes the C4 model as Structurizr DSL, with no model call and no API key. These are the commands used for the example above:

git clone https://github.com/fastapi/full-stack-fastapi-template.git fsft
cd fsft
repowise init --yes --no-prose --no-editor-setup
repowise export --format structurizr --standalone --output ../arch/

Wrote arch\workspace.dsl  (4 containers, 41 external systems, 42 relations)

Open it by pasting into the Structurizr DSL playground, or render it locally with docker run --rm -p 8080:8080 -v .:/usr/local/structurizr structurizr/structurizr local. The generated model carries information C4 has no vocabulary for, written as tags on each box. In this run the backend and the frontend both carry a Hotspot tag, and three of the four containers (the root package, frontend and emails) carry Dead because each contains an unreachable file. Five lines of Structurizr styles colour them.

repowise architecture graph of the repowise repository, showing module clusters sized by file count with import edges between them, the same graph the C4 export is built from

By default the command writes a model fragment you !include from your own workspace.dsl, so regenerating it never overwrites views you wrote. The --standalone flag writes a complete workspace for a first look. The same model is browsable on the web in the architecture views of an indexed repository.

Common C4 mistakes

• Docker containers drawn as C4 containers. A C4 container is a runtime boundary for code or data. Three Docker services running one codebase may be one container, and one Docker image may hold two.
• Components that are a folder dump. A component needs a responsibility you can state in one line, not just a directory name.
• Unlabelled arrows. Every line gets a direction and a verb, and container lines get a protocol.
• Drawing level 4 by hand. It goes stale fastest and IDEs can generate it.
• No legend. A diagram that needs the author in the room is not a C4 diagram by c4model.com's own standard.