C4 Model

Origin & evolution

Simon Brown developed the C4 model from earlier ideas he was working with from around 2006 to 2009, naming the four diagram types in early 2010 and coining the "C4" label in early 2011. The model grew out of a frustration Brown describes in his writing: UML was the dominant notation for software architecture, but most teams produced diagrams that were either incomprehensible to non-engineers or too abstract to be useful during development. The 4+1 model and similar approaches were widely taught but rarely used. Brown wanted something a working engineer could draw on a whiteboard and a stakeholder could read in a presentation without prior training.

The C4 model is notation-independent. You can draw C4 diagrams by hand, in Mermaid, in Structurizr (the accompanying "models as code" toolset Brown built), in draw.io, or in any diagramming tool. That flexibility helped adoption: teams did not need to commit to a specific toolchain to use it. The model is documented at c4model.com, which Brown maintains. A companion book, "The C4 Model", was published through O'Reilly. The approach is now widely used in enterprise engineering organisations and is taught in software architecture courses.

How it works in practice

Each of the four levels serves a different audience and answers a different question.

Level 1, System Context. A single diagram showing the system under discussion, the people who use it, and the external systems it connects to. No internal details. This is the slide you show a business sponsor or a new joiner on day one. A SaaS analytics tool at this level shows the product, the end user, the payment processor, and the data warehouse it syncs to. Everything is a labelled box with a one-line description and an arrow showing the relationship direction.

Level 2, Containers. Zoom into the system boundary. A container is a separately deployable or runnable unit: a web application, a mobile app, a database, a background worker, a message queue. This diagram shows how responsibility is distributed. The analytics tool might show a Next.js frontend, a Rails API, a Postgres database, a Redis cache, and a nightly Python ETL job🔨JobUserJob To Be Done: what the user is trying to accomplishView reference → as five containers with the data flows↕️Data FlowEngineeringA data flow between systemsView reference → between them.

Level 3, Components. Zoom into one container. A component is a grouping of related code with a defined interface: a controller, a service class, a repository layer. The component diagram answers "what are the building blocks inside this container and how do they communicate?" Most teams draw this level for the container that is most actively developed or most complex.

Level 4, Code. Optional. Zoom into one component to show classes, interfaces, or functions. In practice this level is rarely drawn manually; it is more often generated from code or left to IDEs.

A consistent visual vocabulary helps. Every box carries three things: a name, a technology label (if relevant), and a one-sentence description. Arrows carry a label describing the relationship and, optionally, the protocol. Brown's notation guidance fits on one page.

When to use it (and when not)

Reach for the C4 model when a team needs to communicate software architecture to audiences with different levels of technical depth, when a new system is being designed and the team needs a shared mental model, or when onboarding engineers to an existing service.

It earns its keep in medium-to-large systems with multiple containers and clear separation of concerns. It works well in organisations where architecture reviews happen regularly, because the diagrams give reviewers a consistent frame of reference.

It is less useful for very small single-container systems where a System Context diagram and a component list is all that is needed. It is also a poor fit when the architecture is genuinely unstable and changes weekly. Maintaining four levels of diagrams in step with a rapidly mutating system costs more than it returns. In those phases, a whiteboard sketch and a shared understanding often serve better until the design stabilises.

The common failure mode is drawing the diagrams once at the start of a project and never updating them. A C4 diagram that is six months out of date is worse than no diagram, because it actively misleads. Teams that succeed with C4 either automate diagram generation from code (using Structurizr or a similar tool) or establish a lightweight convention for updating the diagrams alongside architecture changes.

In the Unified Product Graph

The C4 model is a tree framework in the engineering category. Its four levels map onto entity types that represent progressively narrower slices of a system:

• The System Context level maps to a bounded_context🔲Bounded ContextEngineeringA DDD bounded context defining a service boundaryView reference → entity, the named system boundary within which the software operates.
• Containers map to service⚙️ServiceEngineeringA deployable service or microserviceView reference → entities, each deployable unit modelled as a node that can carry its own edges and dependencies⛓️DependencyTeam & OrganisationA cross-team or system dependencyView reference →.
• Components map to code_repository💾Code RepositoryEngineeringA source code repositoryView reference → entities, the groupings of related code that live inside a container and expose a defined interface.
• The optional Code level maps to library_dependency📚Library DependencyEngineeringA third-party library dependencyView reference → entities, the fine-grained building blocks (packages, modules, imported libraries) that components rely on.

Modelling the C4 hierarchy this way means a bounded_context🔲Bounded ContextEngineeringA DDD bounded context defining a service boundaryView reference → can link to the team that owns it, a service⚙️ServiceEngineeringA deployable service or microserviceView reference → can carry its deployment📤DeploymentEngineeringA deployment eventView reference → status, and a library_dependency📚Library DependencyEngineeringA third-party library dependencyView reference → can flag a known vulnerability🔓VulnerabilitySecurityA known vulnerabilityView reference →. The diagram becomes a navigable layer of the product graph, where architecture and product context sit alongside each other.