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 | Folded into <doc> | 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.
  • Folded into <doc> — the decision still holds, and its durable rule now lives as prose in a FEATURES / SYSTEMS / DATA_MODELS / OPERATIONS doc. The ADR body is thinned to a Context line plus a pointer to that doc, which is the canonical reference. The decision is not reversed or superseded — only its detailed restatement is consolidated into the doc that owns the rule, to keep the ADR set free of duplicated tables and formulas. The original ADR stays in the repo (append-only); only its body and Status are 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 Folded into multi-regional.md
0002 Terraforming formula model Folded into terraforming.md
0003 Personal reputation tier system Folded into ranking.md
0004 Continuous turn regeneration Folded into turns.md + turn-regeneration.md
0005 Capital Sector and compound sector identity Folded into galaxy.md
0006 Galaxy evolution = region attachment only Folded into galaxy.md
0007 Cargo Wreck mechanic Folded into ships.md
0008 Ship Registry overhaul Folded into ship-registry.md
0009 Quantum Crystal assembly venue split Folded into quantum-resources.md
0010 Warp gate cap formula Folded into warp-gates.md
0011 Warp gate invulnerability window Folded into warp-gates.md
0012 Genesis tier pricing Folded into genesis-devices.md
0013 Advanced Genesis consumption model Folded into genesis-devices.md
0014 Genesis planet-type taxonomy Folded into genesis-devices.md
0015 Solo Genesis no sector lock Folded into genesis-devices.md
0016 Per-player ARIA, no aggregate ML Folded into aria-companion.md
0017 ARIA Consciousness Level 1–5 scale Folded into aria-companion.md
0018 Faction reputation action deltas Folded into factions-and-teams.md (superseded in part by 0032)
0019 Faction reputation decay rule Folded into factions-and-teams.md
0020 Pirate spawn / encounter mechanics Folded into faction-lore.md
0021 Territory taxonomy and influence math Folded into factions-and-teams.md
0022 Rank progression gate model Folded into ranking.md
0023 Turn-cap source canonicalization Folded into turns.md
0024 Personal reputation 8-tier scheme Folded into ranking.md
0025 Personal reputation decay scope Folded into ranking.md
0026 First login fundamentals Folded into first-login.md
0027 Flat is_admin, RBAC dropped Superseded by 0058
0028 Medal storage as association table over JSONB Folded into medal-service.md
0029 Warp Jumper consumption at gate creation Folded into warp-gates.md
0030 Quantum Jump multi-step commit Folded into movement.md
0031 Long-range scanner fuzzy disclosure Folded into sectors.md
0032 Emergent reputation action set Folded into factions-and-teams.md
0033 Astral Mining FactionType promotion Folded into gameplay.md
0034 One-way warp tunnel design Folded into special-formations.md
0035 Dual-ceiling population model (citadel-bound vs habitability-bound) Folded into colonization.md
0036 Phase 3 harmonization atomicity split (HARMONIZING ship status) Folded into warp-gates.md
0037 Lumen Crystal supply economy Folded into quantum-resources.md
0038 ARIA observation-log learning model (Trade DNA retired) Accepted
0039 TradeDock resource atomicity on cancellation Folded into tradedock-shipyard.md
0040 Quantum Jump from Carrier hangar rejection Folded into sectors.md
0041 TradeDock seeding at galaxy generation (Phase 10.5) Folded into galaxy-generation.md
0042 Police engagement spawn-delay mechanism Folded into police-forces.md
0043 Region ↔ Nexus connection is a natural warp in the Frontier outer reaches Folded into region-lifecycle.md
0044 Cluster and Special-Formation naming convention Folded into galaxy.md
0045 Per-player ARIA-driven warp knowledge database Folded into aria-companion.md
0046 Forbid Warp Sink inside Bubble (worldgen invariant) Folded into special-formations-generation.md
0047 Pirate Holdings: pre-seeded hostile sites in the Frontier Folded into pirate-holdings.md
0048 Pirate ecosystem dynamics: self-regulating population Folded into pirate-ecosystem.md
0049 Player-exploit close-outs (Batch 2) Accepted
0050 Provisioning, generation, and lifecycle hardening (Batch 3) Accepted
0051 Scale targets and performance commitments (Batch 4) Accepted
0052 Cross-system contradictions (Batch 5) Accepted
0053 Runtime services (Batch 6) Accepted
0054 Region-lifecycle composition (Group B) Accepted
0055 Destruction-handler composition (Group D) Accepted
0056 Reputation composition + multi-account detection (Group G) Accepted (amended by 0091 — 2026-06-28: additive settle_contest surface)
0057 ARIA security, cost, and isolation invariants (Group L) Accepted
0058 Monetization, admin, webhook security (Group M) Accepted (supersedes 0027)
0059 Governance + citadel-defense fixes (Group I) Accepted
0060 Pirate ecosystem and holdings hardening (Group A) Accepted
0061 Combat correctness and rank wiring (Group C) Accepted
0062 Economy: tariffs, contracts, and market-data hardening (Group F) Accepted
0063 NPC scheduler and lifecycle hardening (Group H) Accepted
0064 Worldgen pipeline cleanup (Group J) Accepted
0065 Schema and data-model parity (Group K) Accepted
0066 Doc philosophy compliance (Group N) Accepted
0067 Tractor / tow / Quantum Jump composition (Group E) Accepted
0068 Player experience and ARIA narration hooks (Group O) Accepted
0069 Bang produces fully-formed region snapshots Folded into bang-import-pipeline.md
0070 Lost clusters and archipelagoes: graph-disconnected formations reachable only via Quantum Jump Folded into special-formations.md
0071 Four-tag version filter: Live, Current, Release, Future Accepted
0072 ARIA course plotting, autopilot, and the chart knowledge economy Proposed — open as of 2026-06-20
0073 Sector celestial composition & planet discovery/naming Folded into star-systems.md
0074 NPC trader economy Folded into npc-traders.md
0075 ARIA route intelligence scope Folded into aria-companion.md
0076 Planetary defense unit pricing Folded into defense.md
0077 Faction mission completion Superseded by 0090
0078 Warp-gate staged construction Folded into warp-gates.md
0079 Haggling numerical model Folded into FEATURES/economy/haggling.md
0080 Siege resolution Folded into defense.md
0081 Ship insurance premium pricing Folded into ship-insurance.md
0082 Citadel safe commodity valuation Folded into citadels.md
0083 Armored mine combat model Folded into combat.md
0084 Planetary registration tiers & registry lookup Folded into genesis-devices.md (amended by 0091 — 2026-06-28: tier set at settle, deployer head-start, Clandestine=hidden)
0085 OAuth tokens out of the redirect URL via single-use code exchange Accepted
0086 Shield-generator build hours Folded into citadels.md
0087 Colony specialization affects defense & research Folded into FEATURES/planets/colonization.md
0088 Genesis deploy restrictions ratified Folded into genesis-devices.md
0089 Player-to-player direct trading Proposed — open since 2026-06-19
0090 Faction reputation is emergent-only Accepted
0091 Site Discovery & Landscape-Driven Citadel Grid Accepted (2026-06-28, Max-approved) — design-only; amends 0056 + 0084

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.