flowCreate.solutions

ADR (Architecture Decision Record) Standard

Architecture Decision Records (ADRs) capture decisions that are easy to lose across PRs, Slack threads, and onboarding.

When to write an ADR

Write an ADR when you are making a decision that is:

  • Hard to reverse
  • Cross-cutting (affects multiple modules/teams)
  • A significant tradeoff
  • Likely to be revisited later (“Why did we do it this way?”)

Examples:

  • Choosing a background job mechanism
  • Picking an auth/session approach
  • Introducing a major dependency or service
  • Changing a data model strategy or scaling approach

Where ADRs live

Multi-repo

  • docs/decisions/

Monorepo

  • System-level decisions: docs/decisions/
  • Module-level decisions: <module>/docs/decisions/

Naming convention

Use:

YYYYMMDD_short_title.md

Example:

20251217_streaming_over_sse.md

Required ADR sections

  • Context: what problem are we solving and why now?
  • Decision: what did we choose?
  • Alternatives: what else did we consider and why not?
  • Consequences: what this enables and what it costs
  • Links: related PRs/issues/docs

Template

Use the ADR template in docs/documentation/templates.md.