C4 Diagrams: A Practical Guide to Mapping Software Architecture

C4 diagrams describe a software system as a hierarchy of maps, each one zoomed in further than the last, so that a non-technical sponsor and a senior developer can both read an architecture without a shared vocabulary of boxes and arrows that nobody defined. The C4 model is an approach to architecture diagramming built on hierarchical abstractions, and it is designed to be easy to learn and friendly to developers. This guide explains the four levels, how to decide which diagrams a project actually needs, which notation rules prevent confusion, and how to stop diagrams drifting away from the code.

TL;DR

• The C4 model describes software through four zoom levels: System Context, Container, Component and Code. Each level targets a different audience.
• Most teams need only System Context and Container diagrams. Component and Code diagrams are drawn when they add value, not by default.
• Every diagram needs a title stating its type and scope, a legend, and labelled relationships. Technology or protocol belongs on container-to-container lines.
• C4 shows static structure only. Dynamic behaviour, data models and enterprise views need complementary notations.
• Diagrams that are generated or derived from a shared model stay accurate far longer than hand-drawn ones.

Table of Contents

• What the C4 model is, and what it is for
• The four levels of C4 diagrams
• Choosing which diagrams to draw
• Supporting diagrams: landscape, dynamic and deployment
• Notation and labelling: what makes a diagram readable
• Showing integrations and legacy systems
• Modelling microservices
• Keeping diagrams current
• The limits of C4
• Our perspective: diagrams as a basis for decisions
• Where we can help
• FAQ
• Sources

What the C4 model is, and what it is for

The C4 model gives a team a common set of abstractions for describing the static structure of a software system, which InfoQ’s overview of the model frames as a ubiquitous language for architecture. The name refers to four levels of detail: Context, Containers, Components and Code. The central idea is that architecture is a set of maps, and that a map is only useful when its scale is declared and its contents are kept to that scale.

This is where C4 differs from the informal whiteboard sketch that most projects accumulate. A typical ad hoc diagram mixes a user, a database, a third-party payment provider, a Java class and a Kubernetes cluster on a single canvas, with arrows whose meaning varies from one line to the next. Such a drawing can be understood only by the person who drew it. C4 constrains the vocabulary: a diagram at a given level contains only elements of the corresponding kind, and the reader always knows what an element is before asking what it does.

The practical uses are consistent across organisations. New engineers use the diagrams to orient themselves in an unfamiliar codebase. Product owners and project managers use the upper levels to understand which systems a change will touch. Architects use them to review a proposed design, and auditors or security teams use them to see where data crosses a boundary. For organisations commissioning external development, a C4 set also becomes part of the handover, a durable description of what was built.

The four levels of C4 diagrams

The four levels are summarised in the table below, following the definitions given in the InfoQ article on the model.

The word “container” here has nothing to do with Docker. In C4 it denotes something that runs and holds code or data: a single-page application, a Spring Boot service, a message broker, a relational database. Readers who come to the model from the container-orchestration world should keep the two meanings apart, since confusing them is one of the more common early mistakes.

Level 1: System Context

The System Context diagram places the system being built at the centre and surrounds it with the people who use it and the other software systems it depends on or feeds. It deliberately contains no technology. A box labelled with a framework name has no place here; the question answered is simply who uses this system and what else does it talk to.

This is the diagram a sponsor can read in thirty seconds, and it is often the most valuable one in a project. It surfaces integration scope early: if a diagram for a new order-management platform shows an ERP, a payment gateway, a courier API and a legacy customer database, the number and nature of those relationships tells a project manager more about effort and risk than any feature list.

Level 2: Container

The Container diagram opens the system boundary. It shows the applications and data stores that together deliver the system, and the connections between them. This is where technology choices appear: a React front end, a Quarkus API, a PostgreSQL database, a message queue. According to the same InfoQ overview, a Container diagram can also show integration technologies such as JSON over HTTPS or XML over HTTPS on the lines between elements.

For most teams, this is the working diagram. It answers the questions that come up in design reviews and incident calls: which service owns this data, what does the front end call, what happens if the queue is unavailable.

Level 3: Component

A Component diagram zooms into a single container and shows the major structural building blocks inside it, such as controllers, service classes, repositories or modules, and how they depend on each other. It is useful when a container is large enough that new developers struggle to find their way around it, or when a modular boundary needs to be agreed before refactoring.

Level 4: Code

The Code level describes classes and their relationships, in effect a UML class diagram or an equivalent. The model’s own FAQ is realistic about its value: according to the C4 diagram FAQ, lower-level diagrams such as Code tend to become outdated quickly, which is why they are better generated on demand from an IDE than maintained by hand. In practice, few teams document this level at all, and that is a reasonable position.

Choosing which diagrams to draw

A frequent misreading of C4 is that a team must produce all four levels for every system. The official guidance on diagrams says otherwise: the levels are optional, only those that add value need be drawn, and System Context and Container diagrams are sufficient for most software development teams.

A workable decision rule follows from that guidance. Begin with a Context diagram for every system, because it is cheap and it fixes the boundary. Add a Container diagram as soon as more than one deployable unit exists. Draw a Component diagram only for the container whose internal structure is a recurring source of confusion, and not for every container. Leave the Code level to tooling.

The following table maps common situations to a sensible starting set.

Supporting diagrams: landscape, dynamic and deployment

Beyond the four core levels, the model defines supporting diagrams. The diagrams page of the model lists the System Landscape, Dynamic and Deployment diagrams.

A System Landscape diagram is a Context diagram without a single focal system: it shows every system and person across an organisation or a domain. It is the natural artefact when the question is how a dozen platforms fit together and which of them overlap.

A Dynamic diagram shows how elements collaborate at runtime for one scenario, as a numbered sequence of interactions. It compensates for the fact that the core diagrams are static, and it is most useful for a flow with several hops, such as an authentication handshake or an order fulfilment path.

A Deployment diagram shows where the containers run. The guidance on deployment diagrams recommends them for illustrating how container instances map onto infrastructure, whether IaaS, PaaS or physical servers, within a specific environment such as production or staging. Because the same container may be deployed differently in each environment, one deployment diagram per environment is the clearest arrangement.

Notation and labelling: what makes a diagram readable

The model is notation-independent. As the notation page explains, it prescribes no particular shapes or colours; it asks instead for consistency across diagrams, clear legends and unambiguous labels. That freedom is convenient, but it means the discipline has to come from the team. A set of rules that works well in practice follows directly from the published guidance.

Every diagram carries a title that states its type and scope, for example “Container diagram for the customer portal”. Without it, a reader cannot tell whether the picture shows one system or an entire estate. Every diagram also carries a key or legend explaining shapes, colours and line styles, even when they seem obvious, because diagrams are circulated outside the team that drew them.

Each element should be labelled with a name, its type and a short description of its responsibility. A box that reads only “Backend” communicates almost nothing; a box that reads “Order service, Container: Spring Boot, validates and stores customer orders” communicates its role, its technology and its boundary.

Relationships deserve the most care. The notation guidance recommends unidirectional lines, labelled consistently with their direction and intent, and requires relationships between containers to name the technology or protocol. A bidirectional arrow with no label hides precisely the information a reviewer needs: who initiates the call, who depends on whom, and over which channel.

A further rule concerns scope. Mixing abstraction levels on a single canvas is, according to the documentation of one C4 drawing tool, the most common C4 mistake, and the remedy is simple: one level per diagram. If a Container diagram begins to include classes, split it.

Showing integrations and legacy systems

Organisations facing integration challenges often find that C4 pays for itself at the upper levels. The System Context diagram shows the system and the other software systems it interacts with, and the Container diagram can state the integration technology on each line, as the InfoQ overview describes.

In a modernisation project this yields a clean method. First, draw the current state: the legacy application as one box, with every system it exchanges data with around it and each line labelled with its protocol and direction. Questions arise immediately: which of these interfaces is documented, which is a shared database accessed directly, which is a nightly file transfer nobody owns. Second, draw the target state at the same level and scope. The differences between the two diagrams form the migration backlog, and the lines that change protocol or direction mark the integration work that needs the most careful estimation.

Labelled direction is especially valuable here. Knowing that the billing system pulls from the CRM, rather than the CRM pushing to billing, determines where retries, authentication and failure handling must live.

Modelling microservices

Microservice architectures raise a practical question: is each service a container or a software system? The guidance on microservices answers that it depends on ownership. Services can be modelled as groups of containers inside one software system when a single team owns them, or as separate software systems when different teams own and evolve them independently.

The consequence is worth thinking through. If twenty services owned by one team appear as twenty software systems, the Context diagram becomes unreadable and hides the fact that they form one product. If services owned by separate teams are lumped into one system, the ownership boundaries, which usually determine where contracts and versioning matter, disappear from the picture. Letting ownership decide keeps the diagrams aligned with how the organisation really works.

Keeping diagrams current

Diagrams rot. A drawing produced during a design phase and never updated eventually misleads more than it informs, and a misleading diagram is worse than none. The model’s FAQ proposes automation as the answer: generating diagrams can keep them up to date, and the approaches it lists include service catalogues, log files or OpenTelemetry data, static analysis, and infrastructure-as-code definitions, as set out in the diagram FAQ.

The practical pattern is to treat the architecture as a model and the diagrams as views of that model. Diagrams defined as text, versioned alongside the source code and reviewed in the same pull requests as the changes that affect them, make drift visible: a change that adds a container without touching the model is easy to spot in review. Tool choice matters less than this principle. Whether the team uses a text-based modelling language, a generator fed from infrastructure definitions or a dedicated drawing tool, the test is whether a change in the system forces a reviewable change in the diagram.

It also helps to be selective. Upper-level diagrams change slowly and justify manual care. Lower-level diagrams change constantly and justify generation or omission. Spending effort evenly across all levels is the quickest way to end with a documentation set that is partly excellent and partly fiction.

The limits of C4

C4 is not a complete architecture description language, and its documentation says as much. The model’s FAQ notes that C4 concentrates on the static structures of a software system, and that other notations, namely UML, BPMN, ArchiMate or entity relationship diagrams, can supplement it when other aspects must be described.

The boundaries are fairly clear. C4 does not model data schemas in depth, so an entity relationship diagram remains the right tool for that. It does not describe business processes in the way BPMN does, and it does not capture enterprise-wide capability or strategy views in the way ArchiMate does. Dynamic diagrams partially address runtime behaviour, but complex state machines or concurrency issues need richer notation. Treating C4 as the backbone of an architecture document, with specialist diagrams attached where they are needed, is more productive than stretching it beyond its purpose. The same FAQ lists Spotify and Decathlon among its case studies, which indicates that the approach scales to large organisations when applied with that discipline.

Our perspective: diagrams as a basis for decisions

We use C4 diagrams in discovery and consulting work because they force the conversation that matters most early in a project: where the boundary of the system lies and what it must integrate with. Because our clients work directly with the engineers who design, build and maintain their software, with no account-manager layer between them, the diagrams are working documents rather than sales artefacts. The engineer who draws the Container diagram is the one who will implement it, and the client can challenge any box or line with the person accountable for it.

Our view is that the value of a C4 set lies in the decisions it makes visible. A Context diagram exposes an integration nobody had budgeted for. A Container diagram exposes a shared database that couples two services which were meant to be independent. A Deployment diagram exposes an environment that differs from production in a way that explains an intermittent defect. These are findings, and for consulting engagements we deliver them as written recommendations, without bias towards any vendor or product, so that the diagrams support the choice of stack rather than the other way round.

We are also sceptical of exhaustive documentation. Drawing all four levels for every container produces maintenance cost and little insight. We favour a small set of accurate diagrams, kept next to the code, reviewed with the code, and detailed only where a team keeps losing time to misunderstanding.

— Pepe F.

Where we can help

Teams that need an architecture mapped, a technology stack chosen or a legacy system assessed before committing budget can work with our engineers through architecture and technology stack consulting. For organisations that want continuing senior technical direction, the CTO subscription plans start with an initial assessment from €3,500 one-off, followed by CTO Advisory from €1,800 per month, Fractional CTO from €4,000 per month or CTO Partner from €7,500 per month.

FAQ

Do I have to draw all four C4 levels?

No. The official guidance states that only the diagrams adding value need to be created, and that System Context and Container diagrams are enough for most teams. Component diagrams are worth adding for a complex container, and the Code level is best generated on demand.

Is C4 the same as UML?

No. C4 is a set of abstractions and a way of structuring diagrams, and it does not prescribe a notation, whereas UML is a full modelling language with its own diagram types. The two can be combined: the C4 FAQ suggests supplementing C4 with UML and other notations when aspects beyond static structure must be described.

How do I show a microservice architecture in C4?

Model services as containers inside one software system when a single team owns them, or as separate software systems when they belong to different teams. Ownership is the deciding factor, and the Container diagram should label each connection with its protocol, for example HTTPS or a message broker.

How do I stop C4 diagrams going out of date?

Derive them from a single model or from sources of truth such as infrastructure-as-code definitions, static analysis or service catalogues, and review them in the same change process as the code. Keep hand-maintained effort for the upper levels, which change slowly.

Sources

• Home | C4 model
• Diagrams | C4 model
• Notation | C4 model
• Deployment diagram | C4 model
• Microservices | C4 model
• Diagram FAQ | C4 model
• FAQ | C4 model
• The C4 Model for Software Architecture, InfoQ
• The C4 model, CRAYON-C4 Docs

This article was produced with AI assistance and reviewed for accuracy. It is provided for general information only and is not professional advice.