The C4 model: context, containers, components and code

Maps of your code

The C4 model is an approach to diagramming software architecture created by Simon Brown. It grew out of the software architecture training he gave from around 2006: according to the C4 site, its roots go back to somewhere between 2006 and 2009, the diagram types were named in early 2010 and the name "C4" was first used in early 2011. Brown had noticed that teams asked to draw their architecture produced diagrams that were hard to understand: unexplained shapes and colours, boxes that could be anything from a class to a data centre, unlabelled lines and several levels of detail mixed on one page. UML, which might have solved the problem, had largely fallen out of everyday use.

His answer was not a new notation but a small set of abstractions and a hierarchy of diagrams built on them, which he compares to the zoom levels of an online map. You start with the whole country, zoom into a city, then a district, then a street. Each level shows a different amount of detail for a different purpose, and you always know which level you are looking at. C4 is deliberately notation-independent and tool-independent: you can draw it on a whiteboard, in a drawing tool or with a modelling tool, provided you follow a few rules.

C4 has become one of the most widely used approaches to architecture diagrams because it is easy to learn, fits naturally with the multi-view thinking of Section 4.2, and produces diagrams that both developers and non-technical readers can follow. In 42010 terms, each C4 diagram type is a viewpoint with its own model kind; C4 just keeps the set small.

The abstractions: people, software systems, containers, components

C4 is built on four abstractions, plus code. A person is a human user of the system: a customer, a courier, a support agent. A software system is the highest level of abstraction, something that delivers value to its users and is typically owned and built by one team or organisation; the food-delivery platform is one, and so are the payment provider and the maps service it depends on.

A container is something that needs to be running for the system to work: in Brown's words, essentially a runtime boundary around some code that is executed or some data that is stored. Examples are a server-side web application, a single-page app running in a browser, a mobile app, a desktop application, a serverless function, a database schema, a file store or a message topic. Each is separately deployable or runnable, and containers communicate with each other across process boundaries, usually over a network.

A component is a grouping of related functionality behind a well-defined interface, living inside a container and running in the same process as the other components there. In a Java service it might be a set of classes behind an interface; in a Node.js service, a module. Components are not separately deployable; the container is the unit of deployment. Finally, code is the classes, functions and tables that implement a component.

Level 1: the system context diagram

The system context diagram is the starting point. It puts the system you are describing in the middle as a single box and surrounds it with the people who use it and the software systems it depends on or that depend on it. It deliberately hides all internal detail, including technologies, protocols and internal services. It answers the questions every newcomer, product manager and security reviewer asks first: what is this system, who uses it, and what does it connect to?

Because it hides internals, the context diagram is also the right diagram for discussions with non-technical stakeholders and for scoping: where does our responsibility end? In the food-delivery example below it immediately shows that card payments, routing and push delivery are bought in, which is architecturally significant (each is an external dependency with its own availability, cost and contract) and invisible in most code-level views.

Level 2: the container diagram

The container diagram zooms into the system box and shows the containers inside it: the applications and data stores that make up the system, what each is responsible for, which technology each uses, and how they communicate. For most teams this is the most valuable diagram they own. It shows the major structural decisions (how many deployable units, which communicate synchronously and which through messaging, which own data) and is concrete enough for developers and operations staff while still fitting on one page.

Notice two choices in the diagram below. The message topic for order events is drawn as a container in its own right, because it is a store that producers write to and consumers read from; the C4 guidance offers this explicit style or, alternatively, omitting the topic and writing "via order events topic" on the arrows. Drawing it shows the coupling through the topic clearly. And the asynchronous relationships use a dashed line, which the key explains. The container diagram says nothing about how many copies of each service run, in which region, or behind which load balancer; that belongs in a deployment diagram.

Level 3: the component diagram

The component diagram zooms into one container and shows the components inside it. It is aimed at architects and developers working on that container, and it is where the internal structure of a service becomes visible: which part handles incoming requests, where the business rules live, which part talks to the database, how events leave the service.

C4's guidance is to draw component diagrams only where they add value, typically for containers that are complex, risky or changed by many people, and to generate them automatically if they are to be kept for a long time, because component structure changes as often as the code does. For the food-delivery platform, the ordering service qualifies: it handles money, talks to an external provider and must publish events reliably. The diagram below shows a typical structure, including an outbox component that writes events to the database in the same transaction as the order and relays them to Kafka afterwards (the outbox pattern is covered in Chapter 6).

Level 4: code, and the supplementary diagrams

The code level zooms into a component and shows its classes, interfaces or tables, usually as a UML class diagram or an entity-relationship diagram. The C4 guidance treats it as optional and generally not worth drawing by hand: most development environments can generate it on demand, and a hand-drawn copy is out of date as soon as someone refactors. Draw it only for the most important or intricate parts, such as a domain model at the heart of the business (Section 4.4 shows such a class diagram).

Three supplementary diagrams fill the gaps the hierarchy leaves. A system landscape diagram is a context diagram without a single system in focus: it shows all the software systems and people in an organisation or domain, which is useful for enterprise and platform architects. A dynamic diagram shows how elements collaborate at runtime for one scenario, as numbered interactions on a container or component diagram (or as a UML sequence diagram); this is C4's equivalent of the scenarios in 4+1. A deployment diagram shows how containers are mapped onto infrastructure in one environment: deployment nodes such as cloud regions, Kubernetes clusters, virtual machines, managed database services and devices, with the number of instances. C4 recommends one deployment diagram per environment that matters, typically production and perhaps staging.

Notation rules that make diagrams readable

C4 does not prescribe shapes or colours, but it does prescribe what every diagram must say. These rules, condensed from the C4 notation guidance, are what make the diagrams above readable without a meeting to explain them.

Tools: drawing versus modelling

C4 diagrams can be produced with any drawing tool, and many teams start with a whiteboard or a general diagramming application. The C4 site distinguishes two families of tools. Diagramming tools draw boxes and lines; they are flexible and familiar, but the diagrams are independent pictures, so renaming an element means editing every diagram that shows it, and nothing checks that the diagrams agree. Modelling tools hold a single model of people, systems, containers, components and relationships, and generate each diagram as a view of that model; renaming happens once, diagrams stay consistent and the model can be queried and validated.

Structurizr, created by Simon Brown, is the reference modelling tool for C4. Its text-based Structurizr DSL describes the model and the views in a file that lives in version control next to the code. Other options include C4-PlantUML (C4 shapes for PlantUML), Mermaid's C4 diagram support and various commercial modelling tools; Section 4.7, Diagrams as code, shows examples. The choice matters less than the habit: keep the source of the diagrams where the team works, and update it in the same pull request as the change it describes.