Also called C4 diagrams, C4 architecture model
In depth The C4 model explained: each level with a real example, notation rules and how to generate the diagrams.
How the C4 model is structured
Simon Brown's C4 model nests four abstractions, and each has a diagram:
| Level | Diagram | Shows |
|---|---|---|
| 1 | System context | Your system, its users, and the other systems it talks to |
| 2 | Container | The separately running parts (apps, databases, queues) and their protocols |
| 3 | Component | The main building blocks inside one container |
| 4 | Code | Classes or tables inside one component; usually generated or skipped |
Three supplementary diagram types sit beside these: one showing all the systems in an organisation, a dynamic diagram of how elements interact for one scenario, and a deployment diagram that maps containers onto infrastructure.
C4 does not fix shapes or colours. It asks that each diagram have a title, a legend, labelled elements with a technology on containers and components, and labelled one-way relationships.
Why the C4 model matters
Architecture diagrams usually fail by mixing zoom levels: a box for a service next to a box for a class and a box for a vendor. C4 gives each audience one level to read. Onboarding reads levels 1 and 2 in minutes. Security reviews trace the lines on level 2 to see what crosses a boundary. Because the model is a hierarchy, diagrams can be generated from structured data instead of drawn by hand, which is the main defence against diagrams going stale.
How to draw C4 diagrams yourself
- Structurizr DSL: define the model once in text and render several views from it. Structurizr Lite runs locally for free.
- C4-PlantUML: C4 macros on top of PlantUML.
- Mermaid: has C4 diagram types, marked beta, so syntax can change.
- Draw.io or Miro with a C4 template: fine for a one-off.
Text-based tools win when the diagram must live in the repo and be reviewed in pull requests. Whichever you pick, a hand-written model still has to be kept in step with the code by someone.
How repowise handles the C4 model
repowise derives the model from the dependency graph and package manifests, with no LLM. The derivation lives in packages/core/src/repowise/core/analysis/c4/ (containers, actors, relations) and the server builds views from it. Containers come from package manifests, with top-level directories standing in when there are none. It draws:
- Level 1, system context: the system plus external systems and actors found in the code.
- Level 2, containers.
- Level 3, components: one box per directory, opt-in on export.
To export:
repowise export --format structurizr
repowise export --format structurizr --standalone --componentsThe default writes a model fragment you !include. --standalone writes a complete workspace with default views (system context, containers, and per-container components when included) that opens in Structurizr Lite. repowise refuses to overwrite a workspace.dsl it did not write unless you pass --force. The architecture page shows the interactive version, and generate C4 diagrams from code walks through a full run.