Architecture diagrams¶
C4 model by Simon Brown, written in PlantUML using the C4-PlantUML macros. Diagrams are committed as .puml source so reviewers can diff them. No rendered SVG artifact is committed or generated in CI.
Why C4 (not UML / arc42 / ad-hoc)¶
- Four levels (Context → Container → Component → Code) matches how engineers actually think about systems — zoom in only where you need detail.
- Plain text source (PlantUML) means diff-friendly, code-review-friendly, no proprietary editor lock-in.
- Adopted in principles.md §2.4 alongside ADRs as the architecture-documentation standard.
Levels we maintain¶
| Level | File | Audience | When to update |
|---|---|---|---|
| L1 Context | context.puml |
Anyone (PMs, ops, security) | A new external system / actor enters the picture. |
| L2 Container | container.puml |
Engineers, ops | A new top-level package (db, http, jobs, …) lands. |
| L3 Component | component-<package>.puml |
Engineers working on that package | Internal architecture changes worth recording. |
| L4 Code | (skipped) | — | Read the code; godoc + per-package AGENTS.md cover this. |
L4 is intentionally omitted. Code is the source of truth for code-level structure; diagrams duplicate and rot.
Rendering¶
# Local render (requires plantuml installed):
plantuml docs/architecture/*.puml
# CI does not render diagrams; review the diffable PlantUML source.
Examples + reference¶
- joelparkerhenderson/plantuml-examples — PlantUML patterns including C4, ERD, mind maps.
- C4-PlantUML library — macros (
Person,System,Container,Rel,Boundary,LAYOUT_WITH_LEGEND). - c4model.com — official model docs.