rgoussu.dev
rgoussu@goussu: ~/library/applicative-architecture
❯ ~/library/applicative-architecture cat architecture-documentation.md

Architecture documentation

# ADRs for decisions, the C4 model for structure — lightweight documentation that stays true because it's cheap to keep.

Conceptsaved 2026-08-08updated 2026-08-20 #architecture#documentation#adr#c4#communication

Overview

Most architecture documentation fails the same way: a heroic wiki written once, wrong within a quarter, distrusted forever. The working alternative is two lightweight, complementary practices — Architecture Decision Records capturing why choices were made, and the C4 model giving structure a consistent set of zoom levels. Both are cheap enough to maintain, which is the only property that matters long-term.

Key points

  • ADRs: one short markdown file per significant decision — context, decision, consequences (including the accepted downsides); numbered, immutable once accepted, superseded rather than edited, living in the repo next to the code they govern. The payoff compounds: every future "why on earth is it done this way?" has an answer, and revisiting a decision starts from its recorded context instead of archaeology.
  • What's ADR-worthy: anything expensive to reverse or repeatedly questioned — datastore choice, sync vs. async integration, build vs. buy, breaking with a convention. Not code style (that's a linter) and not trivia.
  • C4 model (Simon Brown): four zoom levels — Context (system among its users and neighbors), Container (deployable units: services, databases, SPAs), Component (inside one container), Code (rarely drawn — IDEs do it). Each diagram has one level, one audience; the discipline is not mixing altitudes — the exact failure of the classic everything-diagram.
  • Diagrams as text: Mermaid/PlantUML/Structurizr in the repo — versioned, diffable, reviewable in the same PR as the change that invalidates them. A diagram that can't be updated in the PR that breaks it will drift.
  • Living docs over comprehensive docs: a README per service (what, how to run, who owns), ADRs for decisions, C1/C2 diagrams for orientation — and delete what you won't maintain; wrong documentation is worse than none.
  • To explore: arc42 as the fuller template when regulation demands it, RFC/design-doc culture (the proposal stage ADRs formalize), Structurizr DSL for model-based C4.

Practice

  • Write your first ADR (source) — pick a decision already made on a current project and record it: context, decision, consequences — including the downsides you accepted.
  • ADR templates & examples (source) — compare templates (Nygard, MADR…) against your first ADRs and pick a house style.
  • C4 your own system (source) — draw Context and Container diagrams for a system you know; the drill is keeping each diagram at exactly one altitude.
  • Diagrams as text with Mermaid (source) — redo those C4 diagrams as text in the repo, then update one in the same PR as a change that invalidates it.

Related