Public Access

T

BBergleandClaude Opus 5 d3f5ed7e7b 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>

2026-09-20 20:55:30 -04:00

docs

Add planning docs for self-hosted cycling app

2026-09-20 20:55:30 -04:00

.gitignore

Add planning docs for self-hosted cycling app

2026-09-20 20:55:30 -04:00

README.md

Add planning docs for self-hosted cycling app

2026-09-20 20:55:30 -04:00

README.md

bike-app

A self-hosted cycling app: syncs rides from a Bryton Rider 650, tracks mileage like Strava, and adds a spare-parts inventory and a maintenance record with mileage-milestone reminders.

Status: planning complete, no code written yet.

Why

Today the Rider 650 syncs over Bluetooth to the Bryton Active phone app, which forwards to Strava — but Active has no background sync, so you have to remember to open the app. Research found a better path that removes the phone entirely:

ride ends -> Rider 650 joins home Wi-Fi (Main Menu -> Data Sync)
          -> uploads to Bryton cloud
          -> this app's poller fetches the ORIGINAL FIT file
          -> rides, wear tracking, and push reminders

That's also higher fidelity than the current route — Strava's API can only ever return smoothed streams, never the original file.

Docs

File	What's in it
`docs/PLAN.md`	The full implementation plan: stack, schema, ingestion pipeline, auth, notifications, phased roadmap, CI/CD, risks, verification
`docs/RESEARCH.md`	Raw findings: the Bryton cloud protocol (endpoints, headers, auth), FIT library comparisons, maintenance interval tables, self-hostable geo services, Gitea Actions gotchas
`docs/DECISIONS.md`	Every decision taken, what was rejected, and why

Planned stack

Python 3.12 / FastAPI / SQLAlchemy async / PostgreSQL 16 + PostGIS, procrastinate for jobs, SvelteKit static SPA as an installable PWA, MapLibre GL, all behind Caddy in Docker Compose. Source control and CI in self-hosted Gitea with an act_runner on the same box.

Four containers in v1, under 2GB RAM.

Next steps

Verify on the Rider 650: does Main Menu -> Data Sync upload automatically on joining Wi-Fi, or only on manual trigger? This determines how completely the phone leaves the loop.
Plug the 650 in over USB and ls -R the mounted volume to confirm the real .fit path (documented as Bryton/Activities/, but worth confirming).
Grab a real .fit file from it and run it through fitdecode — Bryton's encoder is not Garmin's, and the schema should be checked against reality before it's written.
Then Phase 0: scaffolding and CI (see the roadmap in docs/PLAN.md).