Skip to content

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