# BincioActivity — Ideas & Roadmap

## 1. Strava import from UI ✅

**Goal:** Let users trigger a Strava sync directly from the web UI instead of running CLI commands.

**Current state:** `bincio extract` CLI handles Strava OAuth + sync. The edit server (FastAPI) runs locally.

**Ideas:**
- Repurpose the upload button popup to offer two paths: "Upload file" (existing) or "Connect Strava"
- OAuth flow: open a popup window → Strava auth → redirect back → edit server exchanges code for token → triggers extract
- Edit server would need new endpoints: `GET /strava/auth-url`, `GET /strava/callback`, `POST /strava/sync`
- Progress feedback: SSE (Server-Sent Events) or polling endpoint to stream sync progress back to the UI

**Open questions:**
- Where to store the Strava token? Currently it's a CLI argument / env var. For server mode, probably a local file in the data dir.
- Should sync be incremental (only new activities) or full re-extract?
- How does this interact with multi-user mode (see #2)?

**Effort:** Medium. OAuth popup + SSE progress are the tricky parts.

---

## 2. Multi-user VPS deployment with invite system

**Goal:** Deploy bincio on a VPS so multiple users can have accounts. Invite-only registration.

**Current state:** Entirely single-user, local files, no auth layer at all.

### Clarified model

- A **bincio instance** is a deployment (personal or group)
- **Personal instance:** 1 user, fully self-contained — current state
- **Group instance:** N users, invite-only. All users see each other's public activities by default.
  The `private` flag (already in the schema) means "only me".
- **Federation** is between instances via BAS data URLs — no accounts needed to follow someone
- Data isolation = run your own instance. No per-user isolation within an instance.

### Data layout (multi-user)

```
/data/
  {handle}/          ← one dir per user (extract output)
    activities/
    index.json
    athlete.json
    edits/
    _merged/
instance.json        ← user registry + invite codes
```

The instance's combined feed merges all users' `_merged/index.json` files at render time.

### Auth layer

- Session-based auth added to the edit server (FastAPI handles login/logout)
- Unauthenticated reads stay fully public (static files, same as today)
- Write endpoints check: logged in + owns the activity
- Astro site detects logged-in user to show/hide the Edit button per activity

### Invite system

- Invites: short random codes (8 chars), stored in `instance.json`
- Invite record: `{code, created_by, used_by, created_at, used_at}`
- On registration: validate code → create user dir → mark invite used
- Limits: admin (unlimited), regular users (3 invites, configurable)
- UI: "Your invites" page — generate codes, see who used them

### Render pipeline (multi-user)

- `bincio render` runs `merge_all()` for each user, then builds one Astro site
- Combined `index.json` = all users' public summaries merged, sorted by date
- Per-user profile pages at `/{handle}/` showing only their activities
- Activity detail pages stay at `/activity/{id}/` (IDs are globally unique already)
- Activity cards in combined feed show "by {handle}" label

**Decided:**
- SQLite for user/invite storage (safe under concurrent writes, still no external DB dependency)
- Mastodon-style follow UX: paste a BAS URL into a "Follow" input → instance fetches and caches that feed → activities appear in combined feed with "from {url}" attribution
- Feed refresh: pull-on-demand with cache TTL (no background job — fetch on first stale pageload). [open: exact TTL, stale-while-revalidate vs blocking]

**Effort:** Large. Auth + multi-user render pipeline are the main work. Needs a design pass before coding.

---

## 3. Federation explainer for non-technical users

**Goal:** Write a clear, friendly explanation of how bincio federation works for people who don't know what JSON or APIs are.

**Three ways to share your data:**

### a) Upload raw files
> "Export your GPX/FIT files from Garmin, Wahoo, or wherever, and upload them directly. Bincio converts them automatically."

### b) Upload BAS files
> "Already running bincio locally? Export your BAS data and host it anywhere — GitHub Pages, Netlify, a USB stick. Anyone with the link can include your activities in their feed."

### c) Link to another bincio instance
> "Self-hosting bincio? Just share your URL. Friends can follow you by adding your address to their feeds — no accounts needed, no central server."

**Promo angle ideas:**
- "Your data, your rules. No algorithms, no engagement metrics."
- "Like RSS for your training log."
- "Works offline. Export once, keep forever."
- "Follow friends without either of you needing an account on the same platform."

**Format:** Could be a `FEDERATION.md`, a landing page section, or a one-pager PDF.

**Effort:** Small (writing). Medium if we want a designed landing page.

---

## 4. Mobile data capture & processing

**Goal:** Record activities on a phone, convert to BAS, possibly run the full bincio stack on-device.

**Four sub-questions:**

### 4a. Record on phone
- Standard GPS recording → GPX export is already solved by apps like OsmAnd, Organic Maps, Strava, Komoot
- Could build a minimal PWA (Progressive Web App) that records GPS and exports GPX
- Web Geolocation API + background service worker has limitations (iOS kills background JS)
- React Native / Capacitor would give better background GPS access
- **Simplest path:** just recommend OsmAnd/Organic Maps, skip building a recorder

### 4b. Convert GPX/FIT → BAS on phone
- The extract pipeline is pure Python with no native deps (haversine math, standard library)
- Could run via **Pyodide** (Python in WebAssembly) in a browser/PWA
- Or package as a mobile app with BeeWare/Kivy (Python → iOS/Android)
- Performance: A typical 1-hour FIT file is ~1MB, should parse in <1s even in Pyodide
- **Interesting path:** PWA with Pyodide — no install needed, works in Safari/Chrome

### 4c. Serve the full bincio app on a phone
- The site is a static Astro build — it's already a collection of HTML/JS/CSS files
- A phone could serve these files locally via a small HTTP server
- iOS: no background servers, but a Capacitor wrapper could embed a local server
- Android: more permissive, could run a Python/Node micro-server as a service
- **Alternative:** just open the pre-built site via file:// protocol (may work for static assets)

### 4d. Fully offline mobile app
- Capacitor + the existing Svelte components + Pyodide for extract = plausible stack
- Would need to bundle MapLibre tile data locally (big) or use an offline tile server
- This is a significant project but technically feasible with existing code

**Decided path:**
1. Recommend OsmAnd / Organic Maps for GPS recording — also built a `/record/` page in the app for in-app GPS recording
2. Capacitor wraps the existing Astro/Svelte site as a native iOS/Android app
3. `/convert/` page — Pyodide runs the full extract pipeline in-browser (GPX/FIT/TCX → BAS JSON)
4. Fully offline on-device: needs more work (see below)

**Done:**
- Capacitor setup in `site/` (`capacitor.config.ts`, scripts, packages)
- `/convert/` page with Pyodide (loads bincio wheel, converts files, download or save to cloud)
- `/record/` page with live GPS recording, exports GPX → hands off to `/convert/`
- `POST /api/import-bas` edit server endpoint (accepts pre-converted BAS JSON)
- `site/public/bincio.whl` — bincio Python wheel for Pyodide

**Fully offline — ordered plan:**

| # | Step | Effort | Status |
|---|---|---|---|
| 1 | SW + IndexedDB write (`sw.js`, `localstore.ts`, "Save to device") | Medium | ✅ Done |
| 2 | `dataloader.ts` — runtime-merge server + IDB; update all Svelte components | Medium | 🔄 In progress |
| 3 | Test convert→save→feed loop in browser (`npm run dev`) | Low | Not started |
| 4 | Sidecar merge in JS (port `merge_all`, no Pyodide) | Medium | Not started |
| 5 | Pyodide SW cache (cache CDN assets on first visit) | Medium | Not started |
| 6 | `npx cap add android` + test in Capacitor WebView | Low | Not started |
| 7 | Test on iOS device/simulator | Low | Not started |
| 8 | Native micro-server (only if step 7 reveals SW blocked) | Hard | Contingency |

**`capacitor-nodejs` is not on the roadmap.** If iOS blocks service workers, fallback is a native micro-server or eliminating all remaining `fetch('/data/*')` callsites via step 2.

See `ARCHITECTURE.md` — "Fully offline — missing pieces" for design details and open questions (storage limits, uninstall, sync conflicts).

---

## 5. Gear from Strava export

Import `bikes.csv` and `shoes.csv` from the Strava ZIP export to pre-populate a gear selector
in the edit drawer. The CSV has: Bike Name, Bike Brand, Bike Model, Bike Default Sport Types.
Could store as a `gear.json` in the user's data dir and surface it in the EditDrawer sport/gear fields.

---

---

## 6. User feedback backlog (April 2026)

Items reported via the in-app feedback form.

| # | Who | Area | Description | Notes |
|---|-----|------|-------------|-------|
| F1 | brut | Mobile / Nav | ~~Shorten "BincioActivity" logo to "BA" on narrow screens~~ | ✅ Done |
| F2 | brut | Mobile / Stats | Day-click tooltip in `StatsView` falls off-screen on mobile | Needs viewport-clamping on the tooltip position |
| F3 | brut | Data / Display | Cadence unit "rpm" is wrong for walking and hiking — should be "spm" or hidden | `ActivityCharts.svelte` — sport-aware label or hide tab |
| F4 | brut | Feature | No way to mark an activity as "virtual"; virtual activities should be excluded from records | `virtual: true` sidecar flag + `EditDrawer` checkbox; filter in `RecordsView` and `write_athlete_json` |
| F5 | brut | Charts / MMP | ~~Power curve Y axis should start at 0 W; X axis should extend to at least 2 hours~~ | ✅ Done |
| F6 | brut | Feature | Import gear (bikes, shoes) from Strava export; edit gear; maintenance log with cumulative km | See item 5 above for gear import. Maintenance log is new: date + km + notes per bike |
| F7 | brut | About page | Make user handles in the community tree clickable; show online user count | Handles link to `/u/{handle}/`; online count needs server-side tracking (non-trivial) |
| F8 | brut | Strava sync | ~~Syncing from Strava does not trigger a site rebuild~~ | ✅ Done — trigger was firing after `yield "done"`, client had already closed the SSE connection |
| F9 | diego_p | Data | Check elevation gain on activity `2026-04-11T051441Z` | Likely a GPS artefact or smoothing issue; needs manual inspection |

---

## Prioritization (rough)

| # | Feature | Impact | Effort | Priority |
|---|---------|--------|--------|----------|
| 1 | Strava sync from UI | High | Medium | Soon |
| 3 | Federation explainer | Medium | Small | Soon |
| 4a/4b | Mobile record + convert | Medium | Medium | Later |
| 2 | Multi-user + invites | High | Large | Later (needs design) |
| 4c/4d | Full mobile app | Low | Large | Future |