# 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 — **database choice superseded by D15** **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. The Python/FastAPI half of this still stands. **The database half — Postgres+PostGIS — was replaced with SQLite in D15**, after Phase 0 was already built and merged against Postgres. Kept here, marked superseded rather than deleted, so the PostGIS-specific reasoning (heatmaps, bbox queries, segment matching) is still visible as context for whatever Phase 3 ends up doing about spatial storage without it. ### D5 — procrastinate for background jobs — **needs a replacement, see D15** **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`. `procrastinate` is Postgres-only — no SQLite backend exists, so **D15's move to SQLite invalidates this choice**. Nothing consumes a job queue yet (no ingestion pipeline exists), so this is a deferred decision, not an urgent one: whatever replaces it (APScheduler for a *scheduler*, or a hand-rolled `SELECT ... WHERE claimed_at IS NULL LIMIT 1` polling table for real job durability — SQLite's single-writer model makes even a crude polling table viable at this app's scale) needs picking before Phase 1's ingestion pipeline, not before. ### 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. The time-ranged-association *model* doesn't depend on Postgres. The `EXCLUDE USING gist` constraint enforcing "a component is in exactly one place at a time" does — SQLite has no range types and no exclusion constraints. `component_installs` doesn't exist yet (Phase 2), so this is another deferred casualty of D15, not an active one: the same invariant will need enforcing at the application layer (check-then-insert inside a transaction) instead of the database refusing an overlapping row outright. ### 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. ### D15 — SQLite, single container, no database-level RLS **Chosen:** SQLite as the database, and the whole app (Caddy + API, static web build baked in) as a single container. Made explicitly *after* Phase 0 was already built, tested, and merged against Postgres+PostGIS with a two-role RLS architecture (D4, and the `velodrome_app`/`velodrome_auth` split in `apps/api/velodrome/db.py`) — this is a deliberate reversal of a shipped decision, not a greenfield choice, and it was made with the costs stated plainly first. **Rejected, with reasons on the record:** keeping Postgres as a second container (rejected — explicitly wanted exactly one container total); bundling Postgres+PostGIS *inside* the single container via a process supervisor (offered as the way to get "one container" without losing RLS or PostGIS — rejected in favour of SQLite specifically). **What this costs, stated once here rather than re-litigated every time it's felt:** - **Row-level security is gone.** SQLite has no roles, no session variables, no policy engine — there is no database-enforced layer left, only the repository-layer scope. CLAUDE.md's invariant #4 is revised accordingly (see the file) to describe app-layer scoping as the sole mechanism rather than one of two layers. The user isolation test in `tests/test_auth.py` that used to prove RLS itself now proves the repository-layer scope does the same job in its absence — read it before touching any query that filters by `user_id`. - **PostGIS is gone.** No native geometry columns, no GIST spatial indexes, no `ST_Envelope`. Nothing in the schema uses it yet (Phase 0 has no `activities` table), so this is a live decision for Phase 1/3 to make, not a retrofit — options include SpatiaLite, or storing tracks as GeoJSON/WKB in a `TEXT`/`BLOB` column with spatial math done in application code. - **`procrastinate` is gone** (D5) — Postgres-only, no SQLite backend. Also nothing consumes it yet; a replacement gets picked before Phase 1's ingestion pipeline needs one, not now. - **The `EXCLUDE USING gist` constraint design for `component_installs`** (D8) — doesn't exist yet either (Phase 2); the "one place at a time" invariant will need application-layer enforcement instead of the database refusing an overlapping row outright. **Why proceed anyway:** raised as a concern in-session, with each cost above stated before this decision was made; the user heard the full list and confirmed SQLite regardless. That's their call to make about their own single-user/family-scale instance, not an oversight to correct for them. **What's unchanged:** invariants #1 (raw bytes immutable), #3 (SI integers in storage), #5 (secret containment), #6 (single ingestion path) — none of those were ever Postgres-specific. Auth design (D6, opaque bearer tokens) is unaffected. FastAPI/SQLAlchemy/Alembic stay exactly as chosen in D4; only the database engine underneath them changed. ### D16 — Single-container packaging: entrypoint migrations, tini + a two-line supervisor, Caddy binary copy, Unraid template **Chosen:** one Docker image (root `Dockerfile`), built by copying the SvelteKit static build and the API's venv into a runtime stage alongside a copied-out `caddy` binary. `deploy/entrypoint.sh` runs `alembic upgrade head`, then starts uvicorn (loopback-only) and Caddy as two background processes under `tini` as PID 1, and kills+exits if either one dies. Config surfaces as env vars read by the existing `VELODROME_`-prefixed Pydantic settings; `deploy/unraid-template.xml` exposes the required ones as Unraid Community Applications web UI fields instead of a `.env` file. **Why not a real process manager (s6-overlay, supervisord):** two long-running processes with no dependency graph between them (Caddy doesn't need to wait on uvicorn — it just proxies) doesn't need a supervisor with restart policies, readiness ordering, or log multiplexing. A ~20-line bash script under `tini` (for correct signal forwarding and zombie reaping, which a bare shell script as PID 1 doesn't do) gets the one property that matters — if either process dies, the whole container exits non-zero so Docker/Unraid restarts it — without a new dependency or a config format to learn. Revisit if a third long-running process gets added later; two is the reasonable ceiling for "just write the script." **Why migrations run from the entrypoint, contradicting what apps/api/Dockerfile's own comment used to say** ("Migrations run as an explicit step before this in deploy.yml... never from the entrypoint, so a failed migration fails the deploy visibly instead of crash-looping here"): that comment described the 3-container Postgres plan, where a separate `run --rm api alembic upgrade head` step existed *before* `compose up -d`. A single container has nowhere else to put that step. The property it was protecting — a failed migration must be visible, not silently served — still holds: `set -e` means the script exits non-zero on migration failure, so the container never starts serving traffic and shows as exited/restarting in `docker ps`/Unraid, which is the same visibility by a different mechanism. What's genuinely lost is the *old* mechanism's failure mode of "the previous version keeps running while the bad migration is investigated" — a single container that fails to start migrations has no previous version still up. Acceptable for a single-instance home-lab deployment; would need reconsidering (e.g. a blue/green swap) if this ever needed zero-downtime deploys. **Why the Caddy binary is copied from `caddy:2` rather than using a Caddy base image:** the runtime needs both Python (for uvicorn) and Caddy; picking either official base image as the starting point means installing the other stack into it by hand. Caddy's official images are a single statically-linked Go binary with no CGO, so `COPY --from=caddy:2 /usr/bin/caddy /usr/bin/caddy` into a `python:3.12-slim` base is the documented, standard way to get both without a second package manager or a source build. **Why an Unraid template file, not just documentation:** the earlier decision (in-session) was to move configuration out of a `.env` file and into fields the Unraid web UI can fill in — a plain env var table in a README doesn't do that by itself, since Unraid still needs a `Config`-tagged XML entry per field to render one. `deploy/unraid-template.xml` is that; every field stays hand-editable in the UI afterward regardless of what the template pre-fills, so getting a default slightly wrong here isn't load-bearing. **What this doesn't do:** `.gitea/workflows/release.yml` builds and pushes the image to the Gitea registry; it does not SSH into the Unraid host and recreate the running container. Rolling a new image out is a manual/Unraid-side action (pull + Apply, or Unraid's own update check), not something CI does unattended — consistent with treating "affects a shared, already-running system" as something a human triggers, not automation. --- ## 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* widening of the repository-layer scope (an RLS policy pre-D15; see D15 for why that's no longer the mechanism), never as removal of the default per-user 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.