The C4 model, and when the levels stop paying off.
Four levels of zoom on one system. Two of them get maintained; the other two usually do not.
The C4 model, created by Simon Brown, describes a software system at four levels of zoom. Level 1, System Context, shows the system as one box among the users and external systems it talks to. Level 2, Containers, breaks that box into separately deployable or runnable things: applications, services, databases, message brokers. Level 3, Components, breaks one container into its major internal parts. Level 4, Code, drops to classes and functions. The levels are a zoom control rather than a sequence, and most teams get lasting value from the first two and abandon the last one.
Why context and containers survive and code does not
A context diagram changes when the business changes and a container diagram changes when the deployment topology changes, which is to say rarely enough that a human can keep up. A code-level diagram is invalidated by an ordinary refactor, so it is stale within days of being drawn and nobody trusts it after the first time it misleads them. This is why the honest advice around C4 is to generate level 4 on demand if you want it, and to maintain levels 1 and 2 by hand or by tooling.
The notation is deliberately unspecified
C4 prescribes what each level contains and leaves how it looks to you. There is no required shape vocabulary, no colour rules and no formal metamodel, which is exactly why it spread: it is a way of agreeing what a diagram is about rather than a language you have to learn. The cost of that freedom is that two C4 diagrams from different teams can look nothing alike.
Where it sits against UML and arc42
UML is a formal notation with defined semantics and a large surface area. arc42 is a documentation template covering far more than diagrams, including quality goals, constraints and decisions. C4 is neither: it is a small idea about zoom levels that can sit inside an arc42 document or replace a pile of unlabelled boxes, and its adoption rate relative to UML's is largely a story about how little there is to learn.
How Lucid Train relates to it
The product draws architecture in acts, and the first two, Context and Containers, are C4's first two levels under C4's own names. It does not claim to be a C4 tool: there is no formal C4 metamodel, no level 3 or 4 generation and no validation that a diagram is well-formed C4. What it produces is the pair of views most teams actually keep, generated from the codebase rather than maintained by hand.
The four levels
| Level | Shows | Changes when |
|---|---|---|
| 1 · Context | The system, its users, external systems | The business does |
| 2 · Container | Deployable units and datastores | The topology does |
| 3 · Component | Parts inside one container | The design does |
| 4 · Code | Classes and functions | Any refactor does |
Questions
Related
- What Is an Architecture Decision Record?The code shows what was decided. Only the record shows what was rejected, and why.
- What Is Architecture Drift?Nobody decides to let the diagram go stale. It goes stale because nothing in the process notices.
- What Is Diagram as Code?Text in, picture out. Which means the layout engine, not you, decides what it looks like.
- What Is a Sequence Diagram?Time runs down the page. That single convention is what the diagram is for.
Last updated