bsene C4 Diagram
Workflow
- Pick the C4 level — match diagram depth to the question (see table below)
- Choose the tool — Structurizr DSL by default; Mermaid for quick inline previews (see table below)
- Generate the diagram — follow Diagram Rules, then the DSL reference for the chosen tool
- Render — follow the Rendering fallback chain
C4 Level Selector
| Question type | C4 level | Structurizr view type |
|---|---|---|
| "Show the whole organisation / all systems" | Supporting — System Landscape | systemLandscape (no Mermaid equivalent) |
| "What does this system do?" / "Who uses it?" | Level 1 — Context | systemContext |
| "What are the main services/apps/databases?" | Level 2 — Container | container |
| "How is this service structured internally?" | Level 3 — Component | component |
| "How does this specific class/module work?" | Level 4 — Code | No diagram — Level 4 has no C4 diagram equivalent |
Default to Level 2 (Container) — it covers most "show me the architecture" requests. Level 1 for stakeholder overviews, Level 3 for deep dives into a single service.
Tool Selector
| Need | Use |
|---|---|
| Quick inline preview in chat | Mermaid → references/c4-mermaid.md |
| Export PNG/SVG for docs/wiki | Structurizr → references/c4-structurizr.md |
| Multiple views from one model | Structurizr |
| Organisation-wide system landscape | Structurizr (no Mermaid C4 equivalent) |
| Dynamic / numbered interaction flow | Either (C4Dynamic or Structurizr dynamic) |
| Deployment / infrastructure view | Structurizr (Mermaid C4Deployment is limited) |
| Class/method level detail (Level 4) | Mermaid classDiagram — no Structurizr equivalent |
| No tooling available | Mermaid |
Default to Structurizr DSL unless the user explicitly wants a quick Mermaid preview.
Diagram Rules
- Every element must have: name, type (Person/System/Container/Component), and brief description
- Containers and components must state their technology (e.g. "Node.js Express", "PostgreSQL")
- Every relationship must be labeled with action + protocol (e.g. "Reads events via gRPC", not just "Uses")
- Mark external systems/people with
tags "External"in the model - Boundaries are implicit:
systemContextandcontainerviews auto-scope. Usegroupfor logical sub-groupings within a boundary - Keep diagrams under ~12 elements — split into multiple diagrams if larger
Rendering
Run in order, stop at first success. Native svg/png export does not exist in the Structurizr CLI — always export to PlantUML/Mermaid/D2 first, then render with that tool.
CLI available (binary is
structurizr.shfrom local install / Docker, orstructurizr-clifrom Homebrew/Scoop) — save DSL to/tmp/<name>.dsl, then:structurizr.sh export -workspace /tmp/<name>.dsl -format plantuml -output /tmp/structurizr-out/ # render the .puml to SVG/PNG with `plantuml /tmp/structurizr-out/*.puml`Share output path with user.
Docker available — save DSL to
/tmp/<name>.dsl, give user:# Active replacement (recommended): docker run -it --rm -p 8080:8080 -v /tmp:/usr/local/structurizr structurizr/structurizr local # Legacy (archived but functional): docker run -it --rm -p 8080:8080 -v /tmp:/usr/local/structurizr structurizr/litePoint to
http://localhost:8080.Neither — output DSL as a
```dslcode block. Note: paste athttps://playground.structurizr.com/to render online.
→ Structurizr DSL syntax: references/c4-structurizr.md
→ Mermaid C4 syntax: references/c4-mermaid.md
Benchmark
Scenario: .benchmarks/scenarios/c4-diagram-001-container-view.md · Run: 2026-08-31 · Log: .benchmarks/runs/2026-08-31/c4-diagram-001-container-view.json
| Model | Without | With | Delta |
|---|---|---|---|
| claude-opus-4-8 | 67% | 100% | +33% |
| claude-sonnet-4-6 | 100% | 100% | +0% |
| claude-haiku-4-5 | 100% | 100% | +0% |
PASS (run 2026-08-31). Opus +33 (67→100); sonnet/haiku already at ceiling. No regressions. Gate per
.agents/skills/skill-optimizer/rules/release-gates.md.