Skip to content

Architecture Decision Records

Purpose. Record decisions that would be expensive to reverse, together with the context that made them reasonable at the time.

The rule: ADRs are superseded, never deleted. A record of a decision we later abandoned is often more valuable than the one that replaced it — it stops the same idea being relitigated every six months, and it tells a future reader what we had already considered.

When to write one

Write an ADR when the decision:

  • is costly to reverse (data model, save format, networking authority, module boundaries);
  • has a plausible alternative that a reasonable person would pick;
  • will be questioned later by someone without the context;
  • introduces a third-party dependency;
  • deliberately departs from legacy Applejack behaviour.

Do not write one for a decision that is obvious, cheap to change, or purely stylistic — that belongs in Standards/.

Index

# Title Status Supersedes Superseded by
0001 Plugin-first architecture 🚫 Superseded — 0002
0002 Module architecture 🚫 Superseded 0001 0010
0003 Dual persistence backend ✅ Accepted — —
0004 Item definitions as GameResource assets ✅ Accepted — —
0005 Host-authoritative networking ✅ Accepted — —
0006 Instanced inventory ✅ Accepted — —
0007 Character-pawn binding ✅ Accepted — —
0008 Public repository ahead of v1.0.0 ✅ Accepted — —
0009 Vehicles as a second Ownership consumer ✅ Accepted — —
0010 Runtime plugin loader ✅ Accepted 0002 —
0011 Character creation and multiple characters ✅ Accepted — —
0012 Vehicle entry and driving ✅ Accepted — —
0013 Housing as property groups ✅ Accepted — —
0014 NPC framework: AI and pathing approach Proposed — —
0015 Bail, trials, and sentencing Proposed — —
0016 Sourcing item art from facepunch.sboxassets ✅ Accepted — —
0017 Player character uses the stock Citizen model ✅ Accepted — —

0010 is now written. The next genuinely free ADR number is 0018.

Statuses: Proposed · Accepted · Superseded · Rejected · Deprecated.

Process

  1. Copy ADR_TEMPLATE.md to NNNN-kebab-case-title.md, taking the next free number.
  2. Open it as Proposed and discuss it.
  3. On agreement, set it to Accepted, add it to the index above, and reference it from the relevant Architecture/ document.
  4. To reverse it: write a new ADR that supersedes it. Edit the old one's status and its "Superseded by" row — do not edit its reasoning, and never delete it.