What are the four levels of Simon Brown's C4 model for visualising software architecture, and who is the intended audience for each?

## The problem C4 was invented to solve Most architecture diagrams in the wild are ambiguous: a box might be a server, a process, a library, a class or a team, and an arrow might mean "calls over HTTP", "depends on at compile time" or "sends data to sometimes". Simon Brown's **C4 model** fixes this by defining a small vocabulary of element types and a strict zoom hierarchy, so that the meaning of a box is determined by which diagram you are looking at. The name comes from the four levels: **C**ontext, **C**ontainer, **C**omponent, **C**ode. ## Core vocabulary - **Person** — a human user or role that interacts with the system. - **Software system** — the highest-level unit of delivery; something that provides value to its users. Your system, plus the other systems it integrates with. - **Container** — a separately deployable/runnable thing that executes code or stores data: a server-side web application, a single-page app, a mobile app, a serverless function, an API service, a database schema, a message broker, a file system/blob store. **Important: "container" here has nothing to do with Docker.** A Docker container is one *way* to run a C4 container; the term predates and is broader than the packaging technology. - **Component** — a grouping of related functionality behind a well-defined interface, living *inside* one container and not separately deployable (a package, a module, a service class cluster). - **Code** — classes, interfaces, functions. ## The four levels ### Level 1 — System Context One box for your system in the middle. Around it: the people who use it and the other software systems it depends on or serves. No internal detail at all, no technology choices. **Audience:** everyone, including non-technical people — product owners, business sponsors, new joiners on day one. **Answers:** what is this system for, who uses it, and what does it depend on / what depends on it? ### Level 2 — Container Open the box from level 1. Show every separately deployable/runnable unit and every data store, each labelled with its technology and each connection labelled with its protocol and purpose ("reads/writes, JDBC", "makes API calls, JSON/HTTPS"). **Audience:** developers, architects, operations/support. **Answers:** what is the high-level shape of the system, what technologies are used, how do the parts communicate, and where does data live? For most teams this is **the single most valuable diagram** — the one people actually keep. ### Level 3 — Component Open **one** container. Show the major components inside it, their responsibilities and how they collaborate, plus how they use containers outside (database, other services). **Audience:** developers working inside that container. **Caveat:** you only draw this for containers where it earns its keep. Drawing components for every container is a common way to generate documentation nobody maintains. ### Level 4 — Code Open **one** component and show its classes/interfaces — effectively a UML class diagram. Brown's own advice is that this level should usually be **generated on demand by the IDE**, not hand-drawn and committed, because it goes stale within days and the code itself is a better source of truth. ## Supplementary diagram types C4 is not only the four levels. It also defines: - **System Landscape** — a broader map of many systems in an enterprise and how they relate; wider than context, and typically owned by an enterprise-architecture function. - **Dynamic diagram** — numbered interaction steps between elements (a collaboration/sequence style view) showing how a specific scenario flows. - **Deployment diagram** — maps containers to deployment nodes (physical machines, VMs, Kubernetes clusters, regions), with instance counts; this is where C4 covers the concern that 4+1 calls the physical view. ## Notation rules that make it work C4 is deliberately **notation-independent** — you can draw it in any tool. What it insists on is that every diagram is self-describing: 1. Every diagram has a **title** stating its type and scope ("Container diagram — Internet Banking System"). 2. Every element has a **name, a type (Person/System/Container/Component), a technology** where relevant, and a one-line description. 3. Every relationship arrow is **directed and labelled** with intent and protocol. 4. Every diagram has a **key/legend** explaining shapes, colours and line styles — because the model does not mandate them. A diagram that needs a verbal narrator to be understood has failed the C4 test. ## Comparison with 4+1 | Concern | 4+1 | C4 | |---|---|---| | Functionality / domain | Logical view | Partly Context + Component | | Runtime concurrency | Process view | Not directly; Dynamic diagram covers flows, not threads | | Source/module structure | Development view | Component (and Code) | | Deployment topology | Physical view | Deployment diagram | | Validation flows | Scenarios | Dynamic diagram | C4's differentiator is the **strict abstraction hierarchy with one zoom step per diagram**, which prevents the classic mixed-level diagram where a load balancer, a class and a team all appear as peers. Its weakness relative to 4+1 is that it has no first-class concurrency view. ## Practical trade-offs - **Maintenance gradient:** context and container diagrams change rarely and are worth maintaining by hand; component diagrams change often; code diagrams change constantly. Maintain top-down and generate bottom-up. - **Diagrams as code:** tooling such as Structurizr DSL, PlantUML's C4 macros, Mermaid's C4 support or Likec4 lets you keep one model in version control and render several views from it, which is how teams avoid drift between levels. - **Container ≠ Docker container** is the single most common misunderstanding and a favourite interview trap. - **C4 describes structure, not decisions.** Pair it with Architecture Decision Records (ADRs) for the *why*; a diagram cannot record rationale.