Skip to content

Architecture Decision Records — Personal Training OS

Artifact: ADRs (Phase 3 backfill) — formalizes design decisions D1–D5 from 02-design-schema.md. Date: 2026-07-04

An ADR records one significant decision: its context, the decision, and its consequences. (Convention is one file per ADR; consolidated here for brevity — split later if the log grows.) Status values: Proposed · Accepted · Superseded.

ADR-0001 — Equipment as a constrained multi-select, not a database

Status: ⛔ Superseded by ADR-0006 (2026-07-04) · Traces: EQP-005, DES-D1 (Retained for history. The decision below was reversed — see ADR-0006.) Context: The requirements mandate exactly 15 databases; Equipment is not one. Templates must never assume unavailable gear. Decision: Model equipment as a multi-select whose options are restricted to the available + pending set, so unavailable gear (barbell/kettlebell/net/medicine ball) is unselectable. Consequences: EQP-005/006 satisfied by construction; no validation rule needed. Trade-off: no per-item equipment metadata (purchase date, availability transitions). Revisit if inventory tracking is wanted (a 16th database) — a candidate change request.

ADR-0002 — Times stored as text H:MM:SS with optional numeric seconds

Status: Accepted · Traces: RACE-003, DES-D2 Context: Notion has no native duration type; Goal/Result times need display and occasional math. Decision: Store as text H:MM:SS, plus an optional numeric seconds field where computation (pace, PR comparison) is needed. Consequences: Human-readable and math-capable; slight duplication between the two fields.

ADR-0003 — Two hockey-game relations (Team A, Team B)

Status: Accepted · Traces: HOK-002, DES-D3 Context: Notion relations target one database; the two teams' games live in two separate source-of-truth databases. Decision: Training Sessions carry two relation properties, disambiguated by a Team select. Consequences: Faithful to HOK-002 (no merging source DBs); a single unified relation is impossible without consolidating the sources.

ADR-0004 — Metrics / Check-ins as daily-wide rows

Status: Accepted · Traces: MET-001, DES-D4 Context: Manual daily check-ins vs. high-frequency wearable streams have different shapes. Decision: One wide row per person per day (weight, HR, HRV, sleep, …), optimized for manual entry. Consequences: Ergonomic for v1 manual capture; a long-format companion table is deferred until a real wearable integration lands.

ADR-0005 — Compound seed statuses kept literal

Status: Accepted · Traces: RACE-003, RACE-004, DES-D5 Context: The seed data specifies compound statuses ("Training / Registered", "Registered / Planned"). Decision: Preserve those compound labels as literal select options alongside atomic options. Consequences: Seeds match the requirements exactly; the option list carries some redundancy.

ADR-0006 — Add an Equipment database (supersedes ADR-0001)

Status: Accepted · Date: 2026-07-04 · Supersedes: ADR-0001 · Traces: EQP-001, EQP-002, EQP-004, EQP-005 Context: ADR-0001 modeled equipment as a constrained multi-select to stay within the original 15-database list. On review the PO chose to track equipment as first-class inventory — its own database with availability that changes over time (e.g. the stickhandling ball going Pending → Available), per-item notes, and relations from the things that use it. Decision: Add an Equipment database (a 16th database). Fields: Equipment (title), Category, Availability (Available / Pending / Not available), Location / Notes. Exercise Library, Hockey Drills, and Workout Templates relate to Equipment (relation) instead of a constrained multi-select. A workout/drill's "doable now?" derives from whether all its related equipment is Available (rollup/formula). Consequences: Richer than the multi-select — tracks pending→available transitions and enables a real "currently doable?" signal. Cost: one more database + relations to maintain, and the database count is now 16. EQP-005/006 are satisfied by the Availability field + a doability rollup rather than by omitting options from a list. Requirements impact: the "exactly 15 databases" framing in D1 is void; ARCH-001 ("the full set") still holds — the full set is now 16.