The three views of a system
Every diagram type in CRAYON-C4 answers one question for one audience. Most modeling mistakes come from reaching for the wrong diagram — drawing structure when you meant flow, or logical components when you meant where things run. This page is the map: pick the diagram that answers the question you actually have.
The quick map
| If you need to show… | Use | Answers |
|---|---|---|
| The system in its environment | Context (C1) | Who and what uses this system? |
| What the system is built from | Container (C2) | What are the major runnable parts? |
| The inside of one container | Component (C3) | How is this part structured? |
| Classes and sequences | Code (C4) | How is this implemented? (rarely drawn) |
| How work moves through the system | F4 flow | What happens, in what order, across whom? |
| Where the software runs | Deployment | What runs on which infrastructure? |
The first four are the C4 logical levels. F4 is behavior over that structure. Deployment is a separate axis entirely — covered in its own section below.
The logical structure diagrams (C4)
These describe how the system is arranged — a static, typed reference graph at four nested levels of zoom. See The C4 model for the full picture.
Context (C1) — the system in its world
Intent: orient anyone, including non-technical readers, to what the system is and who it serves. One box for your system, surrounded by people (roles) and external systems. Show: the system as a black box; the actors and neighbours around it. Don't show: anything inside the box — no databases, APIs, or services. Audience: everyone.
Container (C2) — the major parts
Intent: show the separately-runnable/deployable units that make up the system, and how they talk to each other. Show: web apps, APIs, databases, SPAs, message brokers — anything that holds code or data and runs on its own. Label every relationship with purpose and technology. Don't show: where each part runs (that's Deployment) or the classes inside it (that's Code). Audience: technical staff.
Component (C3) — inside one container
Intent: show the major structural groupings inside a single container. Show: the logical building blocks of one container — controllers, services, repositories, adapters. Don't show: every class (over-decomposition), and never more than one container's internals on a canvas. Audience: developers of that container. Draw it only for containers complex enough to warrant it.
Code (C4) — the implementation
Intent: show classes and sequences for a component. Reality: rarely worth drawing by hand — it rots immediately and duplicates what the compiler already knows. Generate it on demand if you need it at all. Audience: developers in that code.
The behavior diagram (F4)
F4 flow — how work moves
Intent: show the dynamic counterpart to C4's static structure — steps, decisions, and hand-offs through swimlanes, over time. Show: who does what, in what order, and where work crosses from one lane to another. Relationship to C4: every cross-lane hand-off implies a C4 relationship. Because F4 shares the C4 model, structure and behavior can't tell two different stories. F4 also projects onto any C4 level, so one authored flow renders at Context, Container, or Component granularity. Audience: anyone reasoning about process, from analysts to developers.
See The F4 flow model for how flow and structure stay in sync.
The deployment diagrams
Deployment answers a different question from everything above: not how the system is logically arranged, but where it physically runs. A Container diagram tells you an API and a database exist and talk; a Deployment diagram tells you the API runs as three pods across two availability zones and the database is a managed Flexible Server with a standby replica.
Why deployment is a separate axis
The C4 levels (Context → Container → Component → Code) zoom through logical structure. Deployment zooms through infrastructure. They are orthogonal:
- A single container (logical) may map to many running instances (deployment).
- One deployment node may host several different containers.
- The same logical model deploys differently per environment — dev on one node, production across a cluster.
This is why deployment gets its own diagram rather than being folded into Container: forcing "where it runs" onto a logical structure diagram is the most common way Container diagrams turn into unreadable mush.
Deployment has its own abstraction ladder
Just as logical structure zooms, infrastructure zooms — and you choose the altitude that suits the audience:
| Altitude | Shows | Example | Audience |
|---|---|---|---|
| Logical / conceptual | Environments and tiers, no vendor specifics | "Web tier → app tier → data tier, across two regions" | Architects, reviewers, customers |
| Platform | Named platform constructs, vendor-aware but not exhaustive | "Container cluster → node pool → pods; managed database with standby replica" | Platform and app engineers |
| Physical / detailed | Concrete instances, sizes, zones, networking | "3 app pods across 2 availability zones; managed database, point-in-time recovery 7 days" | Ops, SRE, anyone provisioning it |
Pick one altitude per diagram, the same way you pick one C4 level per canvas. A conceptual deployment diagram for a customer audience and a detailed one for your SRE team are two different views of the same topology — don't merge them.
Mapping logical to deployment
A deployment node contains instances of containers from your logical model. The link between the two worlds is this containment: a node (or platform construct) hosts one or more deployed container instances. Keeping that mapping explicit is what lets a reader cross from "what the system is" to "where it lives" without guessing.
The full treatment is in The deployment model.
Deployment pitfalls
- Collapsing it into Container. If your Container diagram starts sprouting regions, nodes, and replica counts, split deployment out.
- Mixing altitudes. Conceptual tiers and concrete instance sizes on one canvas serve no single audience well.
- One diagram for all environments. Dev, staging, and production usually differ enough that one diagram either lies about some of them or drowns in conditionals. Prefer a view per environment when they diverge.
- Modeling infrastructure you don't deploy. Show the topology your system occupies, not the entire cloud account.
Choosing under pressure
When you're unsure which diagram you need, ask which question you're answering:
- "Who uses this?" → Context
- "What's it made of?" → Container
- "How is this part built?" → Component
- "What happens, and in what order?" → F4 flow
- "Where does it run?" → Deployment (then pick your altitude)
If a single diagram is trying to answer two of these at once, that's the signal to split it.
Where next
- The C4 model — structure in depth.
- The deployment model — what runs where.
- The F4 flow model — behavior in sequence.
- Glossary — every term defined.