Skip to content

Architecture Decision Records

This directory holds the project's Architecture Decision Records (ADRs). An ADR captures a single architectural decision, the context that prompted it, and the consequences that follow.

ADRs are append-only and immutable. Once an ADR is merged, it is not edited except to update its status. If a decision changes, write a new ADR that supersedes the old one.

When to write an ADR

Write an ADR when the team makes a decision that:

  • Constrains future architecture (technology choice, service boundary, data ownership).
  • Has tradeoffs the team explicitly weighed.
  • Is hard to reverse, or expensive to reverse.
  • Future contributors will benefit from understanding the reasoning behind.

You do not need an ADR for:

  • Routine implementation choices within an already-decided architecture.
  • Bug fixes.
  • Pure refactors that preserve behaviour.
  • Decisions that are obvious from the code itself.

If you're unsure, err toward writing one — they are cheap, and the value comes from having them when you need them.

Format

Use the standard ADR template:

# NNNN — <Title>

## Status

<Proposed | Accepted | Superseded by NNNN | Deprecated>

## Context

What is the situation that prompts this decision? What forces are at play?

## Decision

What did we decide?

## Consequences

What follows from this decision — good, bad, and neutral?

Filenames are numbered and lowercase-hyphenated: 0001-use-multi-regional-architecture.md, 0002-postgres-as-primary-store.md, etc. Numbers are zero-padded to four digits and assigned sequentially.

Lifecycle

  • Proposed — open as a PR for team review.
  • Accepted — merged. The decision stands.
  • Superseded by NNNN — a later ADR replaces this one. The original ADR stays in the repo; only its Status field is updated.
  • Deprecated — the decision no longer applies, and no replacement is needed.

ADRs are never deleted. They are the project's decision history.

Index

Add an entry below for each accepted ADR.

# Title Status
0001 Use multi-regional architecture Stub
0002 Terraforming formula model Accepted
0003 Personal reputation tier system Accepted

Cross-linking

When a SYSTEMS/, OPERATIONS/, ARCHITECTURE/, or FEATURES/ doc rests on an ADR, link to the ADR from that doc. Conversely, ADRs may reference the docs they constrain. See CONTRIBUTING.md → "Cross-linking rules" for the path conventions.