Skip to content

Architecture decision records

An ADR records one architectural decision for Shoehive: the context, the decision, and what it costs us. New ADRs are proposed through a pull request that copies template.md to the next free number (NNNN-short-title.md) with status Proposed. The ADR becomes Accepted when that PR is approved and merged. Once an ADR is Accepted, its Decision section is never edited. Typos, broken links and clarifying notes are fine; changing what was decided is not. To change a decision, write a new ADR that supersedes the old one, then mark the old one Superseded with a link to its replacement. That way the history of why Shoehive works the way it does stays readable. RFC 0001 is the source of truth these ADRs were written against; where an ADR settles a detail the RFC left open, it says so.

# Title Status
0001 Games as typed deterministic state machines Accepted
0002 One shoehive package with subpath exports Accepted
0003 Per-viewer views and JSON Patch sync Accepted
0004 Standard Schema validation for inputs and options Accepted
0005 Mutative drafts with atomic commit Accepted
0006 Seeded RNG, recorded clock and exact replay Accepted
0007 Wallet ledger semantics Accepted
0008 Turns and rounds Accepted
0009 Store interface, snapshot plus log, restart recovery Accepted
0010 Guest identity and resume tokens Accepted
0011 Devtools security model Accepted

Statuses:

  • Proposed: under review, or waiting on a stakeholder decision named in its Open questions.
  • Accepted: in force. Code must follow it.
  • Superseded: replaced by a later ADR, which it links to. Kept for history.