C4 model

The C4 model is a lightweight framework for visualizing software architecture at different levels of abstraction. Created by Simon Brown, it provides a small, shared vocabulary for architecture diagrams so that any team member, stakeholder, or new hire can read them the same way.

The model defines four zoom levels, each aimed at a different audience and trading detail for breadth.

  • Context. Shows the system in its environment, alongside the people and external systems it interacts with. This is the most important diagram and the one teams most often skip. It answers "what does this system do, and who depends on it?" for a non-technical audience.
  • Container. Zooms inside the system to show the applications, data stores, and services that make it up, plus the technology choices behind each. Here a container is anything that executes code or hosts data, such as a web app, an API, a database, or a message broker. It is not a Docker container, despite the shared name. Each container is an independently deployable or executable unit.
  • Component. Zooms inside a single container to show its internal building blocks: components, their responsibilities, and their dependencies. This is the level developers work at day to day.
  • Code. Zooms inside a component to show classes, interfaces, and packages. This level is optional and is usually auto-generated from the codebase rather than drawn by hand, because it drifts quickly as the code evolves.

The Google Maps zoom metaphor is deliberate. Just as a map lets you step from country to city to street, the C4 levels let you step from "the whole system and its surroundings" down to "the classes inside one component". Each level operates at a consistent level of abstraction, and diagrams at a given level never mix in elements that belong to another.

C4 was a reaction against the notational weight of UML, which Brown argued was poorly understood, inconsistently applied, and too often produced diagrams that no one could read. The C4 notation is intentionally minimal: boxes for people, software systems, containers, and components, plus lines for their relationships. It leaves runtime behavior, data flow, and deployment topology to supplementary notations such as sequence diagrams, rather than trying to cover them itself. The C4 levels map roughly onto the high-level design and low-level design split; context and container diagrams are the high-level view; component and code diagrams are the low-level view.

Trade-offs

  • Container name collision. The word "container" predates Docker in this model, but the term is now firmly associated with OS-level containerization. Teams new to C4 routinely expect containers to mean Docker containers, and the confusion never fully goes away.
  • Structural scope only. C4 describes the static structure of a system. It does not model runtime behavior, data flow, deployment topology, or non-functional properties. Brown recommends pairing it with other notations for those concerns rather than stretching C4 to cover them.
  • Level fit. The four levels are a recommendation, not a law. Some teams add a "system landscape" view above Context to map a portfolio of collaborating systems, and many never draw the code level. But systems that don’t decompose into a clean container and component hierarchy can feel awkward to express.

C4 modeling tools

See modeling for broader modeling tools, and diagrams-as-code for the text-based approach that underpins several C4 tools.

  • Structurizr: Developed by Simon Brown, who also created the C4 model, Structurizr is an online diagrams-as-code tool that generates C4 models from a plain-text language, the Structurizr DSL, which is a modeling language in its own right.
  • IcePanel (docs): Features include interactive diagrams that are zoomable into increasing levels of technical detail. Freemium SaaS. You create models of the first three levels of the C4 model: Context, container, component – and then at the bottom you can link to code in GitHub or other repositories.

See also