# 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::::` 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.