Add planning docs for self-hosted cycling app

Planning output only; no application code yet.

Key findings driving the design:

- The Bryton Rider 650 has on-device Wi-Fi (Main Menu -> Data Sync) and
  uploads to Bryton's cloud with no phone and no Bryton Active app. Paired
  with the reverse-engineered Bryton cloud API — which returns the original
  unmodified FIT bytes — this makes ride sync fully hands-off, and higher
  fidelity than the current Strava route (Strava's API cannot return the
  original file, only smoothed streams).
- Build fresh rather than forking Endurain or FitTrackee; borrow Endurain's
  gear/component structure and strava-gear's retroactive time-ranged wear
  computation.
- PWA rather than a native iOS app: iOS 16.4+ gives home-screen PWAs real
  push notifications, which was the only thing that used to force native.

Docs:
  docs/PLAN.md       stack, schema, ingestion, auth, notifications, roadmap,
                     CI/CD, risks, verification
  docs/RESEARCH.md   Bryton cloud protocol, FIT library comparison,
                     maintenance intervals, geo services, Gitea gotchas
  docs/DECISIONS.md  decisions taken, alternatives rejected, rationale

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

docs/DECISIONS.md

@@ -0,0 +1,136 @@
+# 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.