| name | c4-architecture |
| description | C4 architecture diagrams (Context / Container / Component / Code) as Mermaid from the codebase. Use to document architecture, or /c4. Not for codebase discovery (explore) or stakeholder reports (report). |
C4-Architecture
You produce C4 architecture diagrams — the four-level model (Context → Container → Component → Code)
— as Mermaid, from the project's actual structure. It is a low-effort, high-legibility onboarding
artifact every other module can reference. You read the structure (ideally the project-map.md explore
already produced) and emit the diagram at the requested level(s); you do not modify code, and you ground
each box/edge in something real (a service, a dependency, an entry point) — an invented component is worse
than an omitted one.
What this does / does not do
Does: read the codebase structure (or project-map.md), and emit Mermaid C4 at the requested level(s) —
Context (the system + its users + external systems), Container (the deployable apps/services/
stores + how they talk), Component (the parts inside one container), Code (rarely — class-level).
Does not: map the codebase from scratch as a knowledge artifact (that is explore), write a
stakeholder narrative (report), or modify any source.
When NOT to use
- You need to discover the codebase (entry points, conventions, risk files) — that is
explore; C4
consumes its map, it does not replace it.
- You need a prose architecture narrative for stakeholders — that is
report.
Reference Routing
| Situation | Reference |
|---|
| The structure to diagram (preferred input) | state/project-map.md (explore) |
| Avoid reading the whole repo (attention budget) | engine/shared/references/context-degradation.md |
| Receipt write delegation | engine/shared/references/script-delegation-contract.md |
Inputs
| Field | Required | Description |
|---|
level | no | context | container | component | code | all (default: context + container) |
focus | for component | which container to expand (Component level needs a target) |
root | no | the project root (else use project-map.md) |
How to do it
Step 1 — Get the structure
Prefer project-map.md (explore already did the bounded traversal). If absent, read the high-signal
nodes (manifests, entry points, service boundaries) within the attention budget — do not read everything.
Step 2 — Emit the requested level(s)
| Level | Boxes | Edges |
|---|
| Context (L1) | the system as one box + its users + external systems it depends on | who-uses / what-it-calls |
| Container (L2) | each deployable unit (web app, API, worker, DB, queue) | protocol + direction (HTTP, SQL, events) |
| Component (L3) | the major parts inside the focused container | calls / depends-on |
| Code (L4) | class/module level — usually skip (high churn, low value) | — |
Emit valid Mermaid (C4Context/C4Container/C4Component or a flowchart fallback). Ground every box in
a real unit and every edge in a real dependency.
Step 3 — Write the diagram(s) + receipt
Write each diagram to <workspace>/architecture/; mark any inferred box/edge as inferred; write the
receipt.
Output Contract
c4 receipt (<workspace>/receipts/c4-receipt-<timestamp>.json): base + levels (array emitted),
diagram_paths (array), boxes (count), edges (count), inferred (count), source
(project-map|scan), confidence. persistence: Spec-First. The diagrams are the second output.
Proactive Triggers
- A box has no real unit behind it: cut it — an invented container/component misleads the reader more
than an omission.
- Asked for Component level with no focus container: ask which container to expand — Component is
always inside one container.
- The repo is large and there's no project-map: run within the attention budget on high-signal nodes
and record what was not read; consider routing to
explore first.
- Code (L4) requested for a fast-changing codebase: warn that L4 rots quickly — Container/Component
usually carries the value.
Completion Criteria
Done when: the requested C4 level(s) are emitted as valid Mermaid, every box/edge grounded in a real
unit/dependency (inferences marked), written to architecture/, with a receipt.
Not done if: a diagram contains invented components; Component level was emitted with no focus;
source was modified; the whole repo was read when project-map.md was available.
Next step: the diagram is referenced by document/onboarding and report; explore first if the
structure was not yet mapped.
Related Skills
- explore: Maps the codebase (the input). c4-architecture renders that structure as C4 diagrams.
- report: Stakeholder narrative. c4 is the structural diagram a report can embed.
- asset: Renders other visual types; c4 is the architecture-specific diagram producer.
