What is the C4 model for visualizing software architecture?

The C4 model is a lightweight way to describe and diagram software architecture at four levels of zoom: system context, container, component, and code. It exists so that different audiences — from non-technical stakeholders to developers — can look at the same architecture at the level of detail they actually need, instead of one crowded box-and-line diagram that tries to serve everyone. You should use it when you need to communicate how a system fits into its environment and how it is built internally, without committing to a heavy formal notation.

The four levels

The name "C4" comes from the first letter of each level. Each level answers a different question and targets a different audience.

| Level | Shows | Typical audience | Key question it answers | |---|---|---|---|---| | System Context | Your system as a single box, plus the users and other systems it interacts with | Everyone, including non-technical stakeholders | How does this system fit into the world around it? | | Container | The separately deployable/runnable units inside the system (web app, database, service, etc.) and how they talk | Technical people, architects, developers, operations | What are the major building blocks and how do they communicate? | | Component | The components inside a single container and their relationships | Developers and architects | How is this container structured internally? | | Code | Classes, interfaces, and other implementation-level detail | Developers, and usually only for the most important parts | How is this component implemented? |

A useful way to think about it: context is for the whole team and beyond, container is for the technical team, component is for the developers of that container, and code is optional detail you add only where it earns its keep.

Why the levels matter

The main value is abstraction discipline. Informal architecture sketches often mix levels — a database box sitting next to a class, or a user drawn beside a message queue — which makes the diagram ambiguous and hard to read. The C4 model forces you to pick a level and stay there, so each diagram has a clear, consistent meaning.

It also separates structure from notation. The model describes elements (people, software systems, containers, components) and the relationships between them. How you draw them is a rendering choice, not part of the model itself.

One model, many diagrams

A defining property of the C4 model is that the diagrams are views over a single underlying model, not four independent drawings. You define the elements and relationships once, then generate each diagram from that shared model.

This is what Structurizr — the "models as code" tool created by Simon Brown, the author of the C4 model — is built around. You write Structurizr DSL to define the model, and the same model produces multiple diagrams. A minimal example from the project's own documentation:

workspace {
    model {
        u = person "User"
        ss = softwareSystem "Software System" {
            wa = container "Web Application"
            db = container "Database Schema" {
                tags "Database"
            }
        }
        u -> ss "Uses"
        u -> ss.wa "Uses"
        ss.wa -> ss.db "Reads from and writes to"
    }
    views {
        systemContext ss "Diagram1" {
            include *
        }
        container ss "Diagram2" {
            include *
        }
    }
}

Here one set of elements and relationships produces both a system context diagram and a container diagram. Because the diagrams share a model, they stay consistent with each other — change a relationship once and every affected view reflects it. Structurizr also generates the standard C4 diagram types (system landscape, system context, container, component, dynamic, and deployment), and its diagrams are interactive, animatable, and embeddable, with an automatically generated key/legend.

Common pitfalls

• Over-detailing the code level. The code level is the most expensive to maintain and the quickest to go stale. Most teams draw context, container, and component diagrams and add code-level detail only for components where it genuinely helps.
• Mixing abstraction levels. Don't put a class next to a system, or a database next to a person. If you find yourself wanting to, you probably need a second diagram at a different level.
• Treating diagrams as the source of truth. If the diagrams are hand-drawn separately, they drift. Generating them from a single model is what keeps them honest.
• Drawing everything. Not every container needs a component diagram, and not every component needs a code diagram. Diagram what communicates something.

Where to go next

If you want to try the model hands-on, Structurizr provides a DSL tutorial and a browser-based playground, and its text-based format is designed to be easy for both humans and AI agents to parse and validate. The reference implementation is a reasonable starting point if C4-model compliance and compatibility matter to you.