C4 Model Explained: Context, Container, Component and Code Diagrams

The C4 model describes software architecture at four levels of zoom: Context (your system and the people and systems around it), Container (the applications and data stores it is made of), Component (the major building blocks inside one container), and Code (classes and their relationships). It was created by Simon Brown, and its central idea is that you move between levels the way you zoom a map — each level for a different audience. You do not need all four. Its own documentation is explicit that context and container diagrams are enough for most teams.

Live interactive diagramUse the player controls to follow the steps

Internet banking — system contextPlaying silently in this guideWatch with narrationOpen in editor

What this diagram shows

1. This is a C4 Level 1 system context diagram — the whole system as a single box.
2. A person, the personal banking customer, sits outside it.
3. The Internet Banking System is the one software system in scope.
4. Two external systems sit outside the boundary: the Mainframe Banking System and the E-mail System.
5. Every relationship is a labelled arrow, so the diagram reads as sentences rather than a wiring picture.
6. Nothing internal is shown — no services, no databases. That decomposition is the job of the container diagram one level down.

The problem C4 solves

Most architecture diagrams fail in the same way: they mix levels. A cloud region sits beside a Java class, a business capability beside a load balancer, and every reader has to work out which parts are addressed to them.

C4 fixes this with a rule rather than a notation. Each diagram sits at exactly one level of abstraction, and the levels nest: a container diagram zooms into one box on the context diagram; a component diagram zooms into one box on the container diagram. Because the levels nest, a reader always knows where they are.

It is deliberately not a formal language. The official C4 documentation describes it as notation-independent — boxes, arrows and clear labels, readable without a legend. That is the point: it can be drawn on a whiteboard.

One diagram, one level of abstraction. Almost everything else about C4 follows from that rule.

The four levels

Level 1 — System context

One box for your software system, the people who use it, and the external systems it talks to. No internals whatsoever. The audience is anyone who needs to understand scope: an executive, a new joiner, a security reviewer, a supplier.

It is the cheapest diagram to keep accurate, because its contents change rarely. It is also the one that settles the argument nobody realises they are having, which is where the system ends.

Level 2 — Container

Zoom into your system box and show the containers inside it. In C4, a container is not a Docker container — the term predates that usage and means something separately runnable or storable: a web application, a single-page app, a mobile app, an API, a database, a file system, a message bus. The official definition is a thing that needs to be running for the system to work.

This is the most valuable diagram in the set for engineers. It shows the major technology choices, the shape of the system, and how responsibilities are divided — at a level that stays true for months.

Level 3 — Component

Zoom into one container and show the components inside it: groupings of related functionality behind a clear interface. The critical constraint is that components are not separately deployable — the container is the unit of deployment, and all its components run in the same process space. If two things deploy independently, they are containers, not components.

Draw this only for a container complex enough that people get lost in it. It changes with the code, so it is the level that goes stale fastest.

Level 4 — Code

Classes and their relationships, usually as a UML class diagram. C4's own guidance is not to draw this by hand: the detail is already in the code, an IDE can generate it on demand, and a hand-drawn version is wrong within days. Most teams should skip it entirely.

A worked example: internet banking at Level 1

The diagram at the top of this page is the canonical C4 context example, and its restraint is the lesson.

There are four boxes. A person — the personal banking customer. One software system in scope — the Internet Banking System. Two external systems — the Mainframe Banking System and the E-mail System. Every relationship is a labelled arrow, so the diagram reads as sentences: the customer views account balances using the internet banking system; the system gets account information from the mainframe.

What it leaves out is the interesting part. No web server, no database, no microservices, no cloud provider. Those exist, and they belong on the container diagram. Because they are absent here, this diagram can be shown to a bank executive and understood in under a minute — and it will still be correct in two years, when the internals have been rewritten twice.

How to create a C4 model, step by step

1. Name the one system you are describing. If you cannot say it in a sentence, the scope is wrong.
2. List the people who use it, by role rather than by name.
3. List the external systems it depends on or feeds. Anything you do not own goes outside the boundary.
4. Draw the context diagram and label every arrow with a verb phrase, and the protocol where it matters: Sends payment instructions to, over SFTP.
5. Zoom in: list the containers. Apply the test — does it need to be running, or storing, for the system to work? A shared library is not a container. A cron job is.
6. Draw the container diagram inside an explicit boundary, noting each container's technology, and keep the external systems from Level 1 in place so the two diagrams line up.
7. Stop. Go to Level 3 only for a container people genuinely get lost in, and to Level 4 essentially never.
8. Add supplementary diagrams if they help. C4 also defines system landscape, dynamic and deployment diagrams for questions the static four cannot answer.

C4 diagrams you can open and edit

Context and container examples across several domains — all editable.

Building one in Diagramium

The C4 editor ships the model's vocabulary as first-class shapes: person, software system, container, component, external system, database, and a system boundary box that groups containers within one system.

• Draw the boundary first so it sits behind the containers rather than covering them.
• Label every relationship. An unlabelled arrow between two containers is the most common way a C4 diagram loses its value — "these are connected somehow" is not architecture.
• Keep external systems visually distinct so the boundary of your responsibility is obvious at a glance.
• Present the levels in order for a design review — context, then container — so reviewers arrive at the detail already knowing the scope.
• Embed the context diagram in your README or docs site rather than exporting a PNG that silently goes stale. See embedding an interactive diagram.

Best practices

• Every element gets a name, a type and a one-line responsibility. "Orders API" tells a reader less than "Orders API — accepts and validates customer orders".
• Every arrow gets a verb. Direction plus intent, ideally plus protocol.
• Include a title and a date on every diagram. C4 explicitly recommends diagrams stand alone, since they get screenshotted into documents that lose their context.
• Add a legend when you deviate from conventional shapes or use colour to mean something.
• Maintain Levels 1 and 2; let 3 expire. This is honesty, not laziness — a component diagram that is three months old actively misleads.
• Use "container" carefully in conversation. Half your audience hears Docker. Say "application or data store" the first time.

Common mistakes

• Mixing levels in one diagram. A component next to an external system is the failure C4 exists to prevent.
• Confusing containers with Docker containers. A container in C4 is a runnable or storable thing; several may run in one Docker image, and one may run across many.
• Drawing components that deploy independently. Those are containers. If the diagram says otherwise, the diagram is describing a system you do not have.
• Drawing all four levels because there are four. The documentation says to use only the levels that add value, and for most teams that is two.
• Unlabelled arrows. Common, and it removes most of the information the diagram was drawn to carry.
• Putting infrastructure on a container diagram. Regions, clusters and instance counts belong on a deployment diagram.

Related reading

• For the wider set of options — deployment, data flow and sequence views alongside C4 — see software architecture diagram types.
• For ordering and timing, which no C4 static diagram shows, draw a sequence diagram; the notation is standardised by the OMG in UML 2.5.1.
• For a build-oriented walkthrough of a non-C4 system diagram, see how to draw a system architecture diagram.

In short

C4 is a zoom rule with four stops. Keep one level of abstraction per diagram, label every arrow with a verb, draw the context and container diagrams and keep them current, and treat Levels 3 and 4 as things you produce on demand rather than maintain. Two good diagrams that are true beat four that are out of date.

Open the C4 editor to start a context diagram, or open one of the examples above and edit it into your own system.

Questions people actually ask

What does C4 stand for?

Context, Containers, Components and Code — the four levels of the model, in order from most zoomed-out to most zoomed-in.

Is a C4 container a Docker container?

No. In C4 a container is anything that must be running or storing data for the system to work: a web app, an API, a single-page app, a mobile app, a database, a message bus. The term predates Docker's usage and is a frequent source of confusion.

Do I need all four C4 levels?

No, and the model's own documentation advises against it. It states that system context and container diagrams are sufficient for most software development teams; use additional levels only where they add value.

What is the difference between a container and a component?

Deployability. A container is separately runnable or storable; a component is a grouping of functionality inside a container, and all components in a container share the same process space. If two things can be deployed independently, they are containers.

Is C4 a replacement for UML?

No. C4 is a set of abstractions and a zoom convention, deliberately notation-independent, and can be drawn with UML, with plain boxes and arrows, or on a whiteboard. UML is a formal modelling language. They answer different questions and are often used together — the Code level is typically a UML class diagram.

Does C4 cover deployment?

The four core levels describe static structure only. C4 also defines supplementary diagram types — system landscape, dynamic and deployment diagrams — for multiple systems, runtime behaviour and infrastructure respectively.