Guide
The C4 model, as code
The C4 model (Simon Brown's) fixes the worst failure of architecture diagrams — one drawing trying to serve every audience — by splitting the system into four zoom levels: Context, Containers, Components, and Code. Pick the level that answers your reader's question, and stop drawing there.
The four levels
| Level | Shows | Audience |
|---|---|---|
| 1 · Context | Your system among its users and neighboring systems | Everyone — including non-engineers |
| 2 · Containers | The deployable parts: apps, services, databases | Engineers and architects |
| 3 · Components | The building blocks inside one container | The team that owns the container |
| 4 · Code | Classes and functions | Rarely drawn — your IDE does this better |
A C4 diagram example
In Chiltepin, a C4 diagram is a typed c4 block inside Markdown. This is the starter template — a context-level diagram — and the pipeline's real rendered output:
```c4
title: System context
level: context
nodes:
- { id: user, col: 1, row: 1, kind: person, name: Shopper, desc: A customer placing an order. }
- { id: app, col: 2, row: 1, kind: system, name: ShopCo, desc: The retail platform. }
- { id: pay, col: 3, row: 1, kind: external, name: Payment GW, desc: Stripe authorisation. }
edges:
- { from: user, to: app, label: places order }
- { from: app, to: pay, label: authorises }
```Set level: container and the same grammar draws level two — one syntax for the whole model, for you and for your AI agent.
Why C4 diagrams as code
C4's discipline solves what to draw; it doesn't stop the drawing from rotting. A C4 diagram that lives in a drawing tool is stale the week after the architecture changes. As a typed block in your repository, it changes in the same pull request as the change it depicts, chiltepin check fails CI when it references nodes that don't exist, and the rendered SVG is always regenerated from source — the docs-as-code workflow, applied to architecture. If you're modeling a whole system across all levels as its own artifact, Structurizr (from C4's creator) is the specialist tool; Chiltepin's c4 block is for the C4 diagrams that live inside your documents — design docs, service overviews, ADRs — next to the 24 other diagram types those documents need.
Let the agent draw it
Your AI agent already knows your system's actual containers — it can read the code. After npx skills add jdiejim/chiltepin -g (Claude Code, Cursor, Codex, Copilot and 70+ agents), "add a C4 context diagram to the service overview" produces a validated block, not a picture. See the full workflow on the AI diagram generator page.
Frequently asked questions
- What is the C4 model?
- The C4 model, created by Simon Brown, is a way to structure software architecture diagrams as four zoom levels: Context (the system among its users and neighbors), Containers (the deployable parts), Components (the building blocks inside a container), and Code (classes and functions). Each level answers a different audience’s questions, so one diagram never has to serve everyone.
- What is a C4 diagram?
- A C4 diagram is any diagram drawn at one of the four C4 levels using its vocabulary: people, software systems, containers, and components, with labeled relationships between them. A context diagram might show a shopper, the retail platform, and a payment gateway; a container diagram zooms into the platform to show the web app, API, and database.
- Which C4 levels do teams actually need?
- Context and container diagrams carry nearly all the value and are the two worth keeping current. Component diagrams are useful for complex containers; code-level diagrams are almost never worth maintaining by hand, because an IDE can generate them on demand.
- What tools can draw C4 diagrams?
- Structurizr (from the model’s creator) models a system once and projects all four levels from it. General diagram tools (draw.io, Lucidchart) work but validate nothing. Chiltepin treats a C4 diagram as a typed block inside your Markdown docs: the c4 block has a schema for kinds like person, system, and external, chiltepin check validates every node and edge reference, and the diagram renders at build time inside the document it belongs to.
- Can an AI agent write C4 diagrams?
- Yes — this is where typed blocks earn their keep. An agent that reads your repository can write the context and container diagrams as YAML, and because the block has a strict schema, chiltepin check verifies the structure before a human reviews the content. The diagram arrives as a reviewable diff, not a picture.