bike-app/docs/DECISIONS.md

Decisions

Settled during the planning session on 2026-09-20. Each entry records what was chosen, what was rejected, and why — so we don't relitigate them.

---

D1 — Build fresh, don't fork

Chosen: greenfield, borrowing data models only. Rejected: forking Endurain (AGPL, FastAPI+Vue, already has gear/component tracking, but in a feature freeze with a thin maps story) or FitTrackee (AGPL, mature heatmaps, but its "equipment" is one flat tag per workout with no wear intervals — the entire parts/maintenance system would be bolted on anyway). Why: nothing existing covers rides + real parts inventory + maintenance + the self-host features. Take Endurain's gear/component table structure and strava-gear's retroactive wear computation as references; own every line; avoid AGPL entanglement.

D2 — PWA, not a native iOS app

Chosen: SvelteKit static SPA, installed to the iPhone home screen. Rejected: a native SwiftUI app. Why: a home-screen PWA gets the icon, standalone display, offline caching, and — since iOS 16.4 — real push notifications, which was the only thing that used to force native. Native would cost $99/yr for an Apple Developer account, TestFlight/sideloading to reach family phones, and a second codebase forever. The two real PWA gaps on iOS (Web Bluetooth, Background Sync) are irrelevant here: Bryton BLE is a dead end regardless, and the server does all syncing. Kept as insurance: the backend stays strictly API-first with a CI-enforced OpenAPI contract, so if Apple ever makes the PWA route untenable, a native client is a code-generation exercise.

D3 — Bryton cloud poller is the primary ingestion path

Chosen: server-side poller against the reverse-engineered Bryton Active API, every 15-20 min. Rejected: Strava as a source (no export_original — decoded smoothed streams only; plus the June 2026 tier restructure caps new apps at 10 users and requires a paid dev subscription); BLE/ANT-FS direct (nobody has reverse-engineered Bryton's BLE — weeks of work, breaks on firmware updates); depending on the Bryton Active phone app (the original complaint). Why: the Rider 650 has on-device Wi-Fi (Main Menu -> Data Sync) and uploads to Bryton's cloud with no phone involved, and the cloud API returns the original unmodified FIT bytes. That's both zero-touch and higher fidelity than the current Strava route. Fallbacks, both built: USB watch folder (also the historical-backfill mechanism, so it stays exercised rather than bit-rotting) and manual upload.

D4 — Python / FastAPI / Postgres+PostGIS

Chosen: Python 3.12, FastAPI, Pydantic v2, SQLAlchemy 2.0 async, Alembic, PostgreSQL 16 + PostGIS 3.4. Rejected: TypeScript full-stack, Go. Why: fitdecode is Python-only, and the Bryton poller reference implementation is Python (~200 lines of Meteor DDP to vendor rather than reimplement — DDP over SockJS is fiddlier than it looks in JS). FastAPI emits OpenAPI 3.1 for free. PostGIS is needed for heatmaps, bbox queries, and self-segment matching. Go has the best raw performance and a fine FIT library but the weakest data-analysis ecosystem for the later analytics work.

D5 — procrastinate for background jobs

Chosen: procrastinate (Postgres-backed queue). Rejected: Celery (needs Redis/RabbitMQ, heavyweight, weak async, second-class Postgres broker), arq (Redis-only — a whole container for ~50 tasks/day), APScheduler (a scheduler, not a durable queue: no retries, no dead-lettering, no multi-worker coordination). Why: the decisive property is transactional enqueue — the raw_files INSERT and the parse-job enqueue commit atomically on one connection, so there are no orphaned blobs and no jobs pointing at rolled-back rows. That's impossible with a Redis broker without inventing an outbox. It also has built-in cron, which removes the scheduler container, and keeps job state inside the same pg_dump.

D6 — Opaque bearer tokens, no JWT

Chosen: Argon2id passwords + opaque tokens in a sessions table, HttpOnly cookie for the PWA. Rejected: JWT. Why: at 5-15 users, verification is one indexed PK lookup (~0.1ms), and you get instant revocation, a real device list, and no key-rotation or clock-skew bug class. JWT's only advantage is stateless horizontal scale, which will never arrive — choosing it would be a permanent complexity tax against a benefit that never materialises.

D7 — Raw bytes are the only truth

Chosen: every ingested file is written to a content-addressed blob store before parsing, and is never mutated or deleted. All tables are rebuildable projections. Why: this converts "a parser bug wrote wrong elevation to 4,000 rides" and "reprocess a decade of history against a better DEM" from incidents/migrations into routine batch jobs (parser_version bump + requeue). It is the single most load-bearing rule in the design, and it's also the primary data-loss control.

D8 — No odometer column anywhere; wear is derived

Chosen: component_installs as a time-ranged association (strava-gear's model, made relational with a GIST EXCLUDE constraint), with wear computed by replaying the activity stream. Rejected: a stored running odometer per component. Why: correcting "I actually swapped that chain a week earlier" becomes one UPDATE and every downstream number self-corrects. Parts moving between bikes is two rows. A stored counter can do neither without a reconciliation nightmare — which is exactly where FitTrackee's flat equipment tag falls over in year two.

D9 — Streams as columnar int32 arrays

Chosen: one row per channel per activity, values_i32[] with a scale factor. Rejected: a normalized per-sample table (~5x larger with index, and every real query wants the whole stream anyway), JSONB (untyped, 3-5x larger, slow to deserialise), TimescaleDB (solves cross-entity firehose scans; we do per-entity blob reads — and it would mean abandoning the postgis/postgis base image and taking on extension-version coupling at every Postgres upgrade). Bonus: FIT stores position as int32 semicircles, so lat/lon are lossless and free in this encoding. Aggregates are precomputed at ingest into activity_stats, never scanned from streams.

D10 — Imperial display units

Chosen: users.unit_system defaults to imperial. Storage stays SI integers throughout (metres, seconds, mm/s, minor currency units); units are strictly a presentation concern.

D11 — Notification dedupe by cycle sequence

Chosen: notification_log with UNIQUE (user_id, dedupe_key) where the key is service_due:<rule_id>:<component_id>:<cycle_seq>:<threshold> and cycle_seq counts service events logged against that (component, rule). Why: a naive nightly evaluator nags you about the same chain every night until you fix it, and you learn to ignore it. This fires exactly once at 80%, once at 100%, then goes quiet; logging the service increments the cycle and re-arms the next 200 miles. It's how recurrence works without a cron-style recurrence engine.

D12 — ntfy first, Web Push second

Chosen: apprise -> ntfy as the primary notification channel; Web Push (VAPID/pywebpush) as the nicer layer on top; every notification is also an in-app inbox row. Why: apprise is already in the stack for poller alerts and works on iOS with no PWA-install requirement, so notifications can ship early. Apple's web.push.apple.com does speak standard RFC 8291 (no Apple Developer account needed), but only for home-screen-installed PWAs, and iOS silently drops subscriptions after OS updates. Push must never be the only path to the information.

D13 — Monorepo

Chosen: one repo for API + web + deploy + workflows. Why: one maintainer, and API and client change together constantly. D2 removed the only real argument for splitting (a native app would have needed macOS runners that a Linux act_runner can't provide) — now every artefact builds on the same runner.

D14 — Research agent models

Chosen: Opus for the Bryton protocol research and the architecture design (ambiguous, reverse-engineering, synthesis-heavy); Sonnet for the two breadth surveys (existing self-hosted apps, Gitea CI patterns) where material is well-documented and the work is volume.

---

Deliberately deferred

• Routing (Valhalla/Photon/Overpass) — Phase 5, optional. Several GB of RAM for something Komoot already does well.
• Local LLM ride summaries (Ollama) — Phase 4, behind a compose profile.
• Friends/family cross-visibility — Phase 4, as an additive widened RLS policy, never as removal of the default scope.
• Legacy Bryton format support — out of scope entirely. The Rider 650 writes .fit.
• Reverse-engineering Bryton's BLE — explicitly rejected. See RESEARCH.md §1.