C4
Official High Level Overview
- The C4 model is an easy to learn, developer friendly approach to software architecture diagramming:
- Hierarchical abstractions
- Hierarchical diagrams (core)
- Supporting diagrams
- Notation independent.
- Tooling independent.
Context
- Fits team communication, onboarding, alignment with non-developers, and architecture-as-code workflows (e.g. Structurizr DSL) where the same model drives multiple consistent views.
- Sits alongside other diagram idioms: Diagram/Mermaid, D2, diagrams (Python), PlantUML, etc.—C4 answers what to show at which scope, not which renderer to use.
- Complements ADRs, threat modeling, and API catalogs: C4 is primarily structural and decomposition-oriented, not a full security or runtime-behavior notation by itself.
Key principles
- 1. Context — The system as a box among users and external systems; answers what does this software do for whom and what does it talk to.
- 2. Containers — Deployable/runnable things (apps, databases, file stores, browsers, server processes) and how they communicate; answers what are the major pieces that ship or run.
- 3. Components — Logical building blocks inside a single container (services, modules, facades) and their relationships; answers how is this container structured internally.
- 4. Code — Classes, interfaces, files, or modules (UML-style detail is optional here); answers how is a component implemented—often skipped or generated when auto-layout or IDE views suffice.
- Notation discipline — Prefer simple shapes (person, software system, container, component), clear relationships (sync/async, protocols where useful), and explicit scope so diagrams stay readable.
Mechanism
- Zooming in adds detail inside a boundary drawn at the previous level: a system in context becomes a container diagram; a container becomes a component diagram.
- Supplementary views (deployment, dynamic sequences) are add-ons when needed; the core model stays structural and static at each level.
- Tooling can validate that elements exist at the right level and that relationships are consistent across views—this is where architecture-as-code shines.
Examples
- Structurizr — DSL and exports aligned with C4 views (context, container, component, deployment, etc.).
- Diagrams-as-code in Mermaid or PlantUML often imitate C4 levels even when not using a C4-specific toolchain—same separation of concerns, lighter enforcement.
Misconceptions
- “C4 is four mandatory diagrams for every system” — Overstated; the levels are lenses. Teams routinely omit code-level C4 or collapse steps when the audience does not need them.
- “C4 replaces UML” — Misleading; C4 overlaps some deployment/component ideas but aims at communication defaults, not full behavioral or formal modeling.
- “If it’s not C4, it’s wrong” — False; many good architecture descriptions use other abstractions (DDD bounded contexts, data flows, threat surfaces). C4 is one structured option.