bincio-activity/docs/mobile-app.md

# Bincio Mobile App — Design Document

## Vision

The long-term goal is full independence from Garmin Connect, Strava, Hammerhead,
and similar platforms. Today those platforms act as mandatory intermediaries: your
device syncs to their cloud, you authorise third parties to pull from their API,
and your data effectively lives on their servers.

The Bincio mobile app removes that dependency:

- Your FIT/GPX/TCX files live on your device.
- The app reads them directly — no platform sync required.
- A Bincio instance (bincio.org or self-hosted) is an optional upgrade for backup,
  sharing, and web access — not a prerequisite.
- Devices like the **Karoo 2** (Android-based) are a first-class target: activities
  are already saved locally as FIT files, so the app can pick them up directly from
  the filesystem without any export step.

This initial version focuses on **post-ride import and local storage**. Live
recording (GPS + sensors during a ride) is the long-term goal that would complete
full platform independence, but it is out of scope until the foundation is solid.

---

## Philosophy

**Local-first.** All activity data lives on the device. The app works fully offline
— no account, no internet connection, no platform authorisation required.

**Original files as source of truth.** The raw FIT/GPX/TCX file is always stored on
device alongside the extracted BAS JSON. This means:

- You can re-extract at any time (e.g. when the algorithm improves, or to apply DEM
  correction after connecting to an instance).
- Sync to a remote instance is just pushing the original file — the server
  re-extracts with the full Python pipeline.
- No data is ever locked into a proprietary representation.

**The algorithm travels to the data — not the other way around.** When internet is
available, the app downloads a fresh copy of the extraction algorithm from bincio.org
and runs it locally. Your activity files never touch the server. Only the Python
wheel (the code) is downloaded; the data stays on device.

**Sync is optional and explicit.** Connecting to a Bincio instance adds cloud
backup, the web feed, and sharing. The app never silently overwrites local data.
Sync is user-initiated.

**Open format.** Activities are stored in the BAS schema — the same JSON format the
server uses. Any tool in any language can read them.

---

## Development setup

### Two build modes: Expo Go vs Development Build

This is the most important thing to understand before starting.

**Expo Go** is the Expo app available on the Play Store / App Store. It runs any
Expo project by scanning a QR code — no compilation step. However, it only supports
Expo's own built-in modules. It does **not** support third-party native modules.

**Development Build** is a custom version of the Expo Go app compiled specifically
for this project. It includes all third-party native modules (react-native-webview,
maplibre, react-native-svg). It is installed once on the device; after that, code
changes still update instantly via Metro (the JS bundler) — no rebuild needed.

| | Expo Go | Development Build |
|---|---|---|
| Setup | Scan QR, instant | Build APK once (local or EAS cloud) |
| expo-sqlite | ✅ | ✅ |
| expo-document-picker | ✅ | ✅ |
| react-native-webview (Pyodide) | ✗ | ✅ |
| @maplibre/maplibre-react-native | ✗ | ✅ |
| react-native-svg | ✗ | ✅ |
| Code changes | instant (Metro) | instant (Metro) |
| Native changes | need new Expo Go release | rebuild APK |

**Phase 0 and 0.5** only use built-in Expo modules — Expo Go works. **Phase 1**
(Pyodide) and **Phase 4** (MapLibre maps) require a Development Build because
`react-native-webview` and `@maplibre/maplibre-react-native` are native modules.

The preferred path for Phase 1+: connect the phone via USB and run
`npx expo run:android` once. After that, JS changes still update instantly via Metro
— no rebuild needed unless you change native code.

---

### Prerequisites

| Tool | Required for | Install |
|---|---|---|
| Node.js 20 LTS | everything | [nodejs.org](https://nodejs.org) or `nvm install 20` |
| npm | everything | ships with Node |
| JDK 17 | Android builds | `brew install --cask zulu@17` |
| Android Studio + SDK | Android dev build / emulator | [developer.android.com/studio](https://developer.android.com/studio) |
| Xcode 15+ | iOS only, macOS only | App Store → `xcode-select --install` |
| EAS CLI | cloud builds (optional) | `npm install -g eas-cli` |

You do **not** need a physical Android device to start. The Android emulator
(AVD Manager inside Android Studio) works fine for development.

After installing Android Studio, create `mobile/android/local.properties`:

```
sdk.dir=/path/to/Library/Android/sdk
```

---

### First-time setup

```bash
# From repo root:
cd mobile && npm install
```

---

### Local dev with a phone on WiFi

To test sync against a locally running bincio instance from a phone on the same
WiFi network:

```bash
./scripts/dev_test.py --mobile
```

This binds the API server to `0.0.0.0` (all interfaces) instead of `127.0.0.1` and
prints the LAN IP to use as the instance URL in the app settings. The mobile option
detects the local IP automatically via a UDP socket trick.

---

### Phase 0 — Expo Go (quickest start)

Since Phase 0 uses only built-in Expo modules, you can start with Expo Go:

```bash
cd mobile
npx expo start
```

1. Install **Expo Go** on your Android phone from the Play Store.
2. Scan the QR code printed in the terminal.
3. The app loads instantly. Code changes in your editor appear on the phone
   within a second or two.

> **Limitation**: once you add the Pyodide WebView in Phase 1, you must switch to
> a Development Build. Expo Go will show an error for `react-native-webview`.

---

### Phase 1+ — Development Build

#### Option A: local build (Android Studio required)

Plug in an Android device via USB (or start an emulator in Android Studio), then:

```bash
cd mobile
npx expo run:android          # builds APK, installs it, starts Metro
```

This compiles the full native project once (~3–5 min). After that, JS changes
reflect instantly without rebuilding.

For the emulator, create an AVD in Android Studio with API 33+ and start it before
running the command.

#### Option B: local EAS build (no Android Studio, no external cloud)

`eas build --local` runs the entire build pipeline on your own machine (or VPS):

```bash
npm install -g eas-cli
eas build -p android --profile development --local
```

This produces an `.apk` you can transfer to the device via any means (USB, VPS
download link, AirDrop). No Expo account or cloud service required.

---

### iOS development (macOS only)

```bash
cd mobile
npx expo run:ios --udid <device-udid>
```

Requires Xcode 15+ and an iOS platform SDK matching the device's iOS version
(Xcode Settings → Platforms). After initial build, JS changes update via Metro.

MapLibre on iOS requires the following in `ios/Podfile`'s `post_install` block:

```ruby
$MLRN.post_install(installer)
```

This lets MapLibre inject its Swift Package Manager framework dependency. Without
it, the build fails with `MLNNetworkConfiguration.h not found`.

Cloud builds via EAS:

```bash
eas build -p ios --profile development   # requires Apple Developer account ($99/yr)
```

---

### Where Pyodide comes from

The hidden WebView loads Pyodide from the **jsDelivr CDN** — the same source
as the `/convert/` page on the web:

```
https://cdn.jsdelivr.net/pyodide/v0.26.4/full/pyodide.js  (~30 MB)
```

On first extraction after install, the WebView downloads and caches this
runtime in `expo-file-system`'s document directory. Subsequent extractions use
the cached copy — no internet required.

The **bincio wheel** (~50 KB) is fetched from:

```
GET {instance_url}/api/wheel/version   → { version, url, api_url }
GET {instance_url}/bincio-{version}-py3-none-any.whl   (nginx, prod)
GET {instance_url}/api/wheel/download                  (FastAPI, local dev)
```

If no instance is configured, it falls back to `https://bincio.org`. The wheel
is also cached locally and re-downloaded only when the version changes.

**Summary of what touches the network:**

| Asset | Size | When | Cached |
|---|---|---|---|
| Pyodide runtime | ~30 MB | once (first extraction ever) | ✅ permanently |
| Common packages | ~5 MB | once | ✅ permanently |
| bincio wheel | ~50 KB | on version bump (bundled fallback in assets/) | ✅ until next update |
| Map tiles | per-tile | on pan/zoom | ✅ by MapLibre |

Everything else — the activity files, the extracted BAS JSON — stays on device.

---

### Building a standalone APK

A standalone APK is a **self-contained application binary** that runs without Expo Go and doesn't rely on development servers. Use this to distribute to friends, devices, or the Karoo 2.

#### Option A: EAS cloud build (recommended, no local tools needed)

```bash
npm install -g eas-cli
eas build -p android --profile preview   # produces a standalone APK
```

The APK is available for download from the EAS dashboard or via:
```bash
eas build -p android --profile preview --wait
eas artifact download                     # follow the prompt
```

#### Option B: Local build with prebuild (requires Android Studio)

```bash
cd mobile
npx expo prebuild --clean                 # generates Android native project
cd android
./gradlew assembleRelease                 # builds release APK
```

The APK is at `android/app/build/outputs/apk/release/app-release.apk`.

**Note:** Release APKs must be signed. If signing fails, use `assembleDebug` instead to produce `app-debug.apk` (same as `npx expo run:android`).

#### Karoo 2 sideloading

The Karoo 2 (Hammerhead, Android 8.1, armeabi-v7a) is supported. Two build fixes
are required and already applied to `android/app/build.gradle`:

1. **JS bundle in debug APK** — `debuggableVariants = []` in the `react {}` block.
   Without this, the debug APK looks for Metro on `localhost:8081`, which doesn't
   exist on the Karoo, and the app hangs on the splash screen with
   `Unable to load script`.

2. **armeabi-v7a native modules** — `splits.abi` must include `"armeabi-v7a"`.
   Without it, the CMake build for `libappmodules.so` (the TurboModule registry)
   only runs for arm64-v8a. On the Karoo the app crashes with
   `PlatformConstants could not be found`.

To build and install on a connected Karoo:

```bash
cd mobile/android
./gradlew assembleDebug
adb -s <karoo-serial> install -r app/build/outputs/apk/debug/app-universal-debug.apk
```

Find the Karoo serial with `adb devices -l`.

#### Troubleshooting

If your friend's APK won't start:

1. **Check device logs:**
   ```bash
   adb logcat -s ReactNativeJS AndroidRuntime  # requires Android SDK tools
   ```

2. **Ensure minimum Android version:** The app requires Android 5.0 (API 21) or higher.

3. **`Unable to load script` (splash hang):** Debug APK is trying to reach Metro.
   Ensure the build was compiled with `debuggableVariants = []` in `build.gradle`.

4. **`PlatformConstants could not be found` (crash on start):** `libappmodules.so`
   is missing for the device's ABI. Add the ABI to `splits.abi` in `build.gradle`.

5. **Verify the APK is actually installed:**
   ```bash
   adb install /path/to/app.apk
   ```

---

### Distributing the app

| Target | Method |
|---|---|
| Your own Android phone | `npx expo run:android` via USB, or `eas build --local` |
| Friends or testing | Standalone APK (release or debug, see above) — no Expo Go needed |
| Karoo 2 | `eas build -p android --profile preview` → sideload via `adb install` |
| Other Android users | Share the standalone APK download link |
| Play Store | `eas build -p android --profile preview` → upload `.aab` to Play Console |
| iOS users | `eas build -p ios --profile preview` → TestFlight (beta) or App Store |

---

## Repository layout

```
bincio_activity/
├── bincio/               — Python server + extractor
│   └── serve/server.py   — FastAPI server (includes mobile API endpoints)
├── site/                 — Astro web frontend
├── mobile/               — Expo React Native app  ← this document
│   ├── app/
│   │   ├── (tabs)/
│   │   │   ├── index.tsx     — Feed screen
│   │   │   ├── import.tsx    — Import screen
│   │   │   └── settings.tsx  — Settings screen
│   │   └── activity/[id].tsx — Activity detail screen
│   └── db/
│       ├── index.ts      — SQLite schema migrations
│       ├── queries.ts    — typed query helpers + React hooks
│       └── sync.ts       — bidirectional sync logic
├── scripts/
│   └── dev_test.py       — local dev runner (--mobile binds to 0.0.0.0)
└── docs/
    └── mobile-app.md     — this document
```

---

## What already exists

| Piece | Where | Notes |
|---|---|---|
| BAS schema | `docs/schema.md` | The on-device data format — identical to the server format |
| Pyodide-based extraction | `site/src/pages/convert/` | FIT/GPX/TCX parsing via CPython→WASM in the browser — **the proof of concept for mobile extraction**. A hidden WebView uses the same mechanism. |
| Bincio wheel | `dist/bincio-0.1.0-py3-none-any.whl`, served at `/bincio-0.1.0-py3-none-any.whl` | Pure-Python wheel already downloaded and run by the `/convert/` page |
| Local storage concept | `site/src/pages/convert/` | IndexedDB + service worker in the web app. Mobile uses SQLite instead. |
| Content-addressed dedup | `bincio/extract/dedup.py` | `source_hash` (SHA-256 of raw file) prevents duplicates |
| REST API | `bincio/serve/server.py` | Login, upload, activity detail, feed — sync primitives |
| Settings table | `bincio/serve/db.py` | Key/value settings in the server DB; same pattern used on device |

---

## Technology

### Framework: Expo (React Native)

- TypeScript throughout
- `expo-sqlite` v2 — on-device SQLite with WAL mode
- `expo-document-picker` — file picking from device storage
- `expo-file-system/legacy` — filesystem access (legacy import required with Expo SDK 54+)
- `react-native-webview` — hidden WebView for Pyodide (Phase 1)
- `@maplibre/maplibre-react-native` v11 — interactive maps, dark CartoDB tiles
- `react-native-svg` ≥ 15.15.4 — SVG area charts; **must be ≥ 15.15.4** (earlier
  versions crash in React Native New Architecture / Fabric)
- `expo-background-fetch` + `expo-task-manager` — background directory polling (Android, Phase 2)
- `expo-notifications` — import notifications (Phase 2)
- EAS Build — iOS and Android binaries; APK sideloading for Karoo

### React Native New Architecture (Fabric)

The app runs with `newArchEnabled=true` (React Native New Architecture). This is
required for compatibility with the MapLibre native module. Key implication:
`react-native-svg` must be **≥ 15.15.4** — earlier versions crash on startup in
Fabric with a `RNSVGUseProps::~RNSVGUseProps()` / `folly::dynamic::destroy()` error.

### MapLibre v11 API

`@maplibre/maplibre-react-native` v11 changed from a default export to named exports:

```typescript
// v11 — named imports required
import { Camera, GeoJSONSource, Layer, Map } from '@maplibre/maplibre-react-native';

// Map props: mapStyle (not styleURL), dragPan/touchZoom/touchPitch/touchRotate
// Camera: initialViewState.bounds = [west, south, east, north]
// No scrollEnabled prop — use dragPan={false} instead
```

---

## Extraction: Pyodide in a hidden WebView

The `/convert/` page already demonstrates that the full Python extraction pipeline
runs in a browser via **Pyodide** (CPython compiled to WebAssembly). A React Native
app can host a hidden `WebView` running the exact same environment. No rewrite of
the extraction logic is required.

### Package stack (proven in /convert/ today)

```
Pyodide v0.26 (CPython → WASM, ~30 MB)
├── lxml        — pre-compiled WASM in Pyodide (XML / GPX parsing)
├── fitdecode   — pure Python, installed via micropip (FIT parsing)
├── gpxpy       — pure Python, installed via micropip (GPX parsing)
├── pyyaml      — pure Python, installed via micropip
└── bincio wheel — pure Python, fetched from bincio.org
```

Every dependency is either pre-compiled in Pyodide or **pure Python with no C
extensions**. Nothing needs recompilation for mobile.

### Data flow

```
React Native
  1. Read file bytes from device filesystem (expo-file-system)
  2. postMessage({ type: 'extract', filename, bytes }) → hidden WebView

Hidden WebView (Pyodide)
  3. Write bytes to Pyodide virtual FS (/tmp/activity.fit)
  4. Run Python extraction → BAS dict (detail + timeseries + geojson)
  5. postMessage({ type: 'result', detail, timeseries, geojson }) → RN

React Native
  6. Store detail_json, timeseries_json, geojson in SQLite
  7. Copy original file to app storage → record path in DB
```

**Data never leaves the device.** Network traffic: only the Pyodide runtime
(~30 MB, CDN, cached once) and the bincio wheel (~50 KB, from bincio.org, updated
on version bump).

### Performance

| Scenario | Time |
|---|---|
| First extraction (cold Pyodide + packages) | ~5–8 s |
| First extraction in session (warm WebView) | ~1–3 s |
| Subsequent extractions (warm WebView) | ~0.5–1 s |
| Pyodide RAM while active | ~100–150 MB |

For batch import the WebView is kept alive across files; per-file cost drops to
the Python execution time only.

---

## Karoo 2: hardware and OS constraints

The Karoo 2 (Hammerhead, Android 8.1 / API 27 / Chrome 61 WebView, armeabi-v7a) is the primary Android target that drove most of the implementation decisions in this app. It surfaces three independent hardware limitations that affect the app design.

---

### 1 — No WebAssembly.Global (Chrome 61)

**Symptom:** `TypeError: WebAssembly.Global is not a constructor` in the Pyodide WebView shortly after mounting.

**Root cause:** `WebAssembly.Global` was added in Chrome 69 (Android 10 / API 29). Chrome 61 — the system WebView that ships with Android 8.1 — does not have it. Pyodide requires it for internal module linking. There is no JavaScript-level polyfill for this primitive; it must be provided by the JS engine.

**Implementation:**

`PyodideWebView.tsx` checks for the primitive at init time before attempting the 30 MB Pyodide download:

```javascript
if (typeof WebAssembly === 'undefined' || typeof WebAssembly.Global === 'undefined') {
  _post({ type: 'engine_unavailable', reason: 'wasm_global' });
  return;
}
```

`extractActivity.ts` also gates at the module level using the API level so the WebView is not even mounted on old Android:

```typescript
let _engineUnavailable = Platform.OS === 'android' && (Platform.Version as number) < 29;
```

The `isEngineAvailable()` export returns `true` (ready), `false` (unavailable/error), or `null` (still initialising). The Import screen uses this to decide the extraction path.

**Fallback:** server-side extraction (see next section).

---

### 2 — GPU driver crash (OpenGL / SurfaceView)

**Symptom:** `Fatal signal 11 (SIGSEGV), code 2, fault addr 0xa7xxxxxx in tid RenderThread` — the app crashes within seconds of mounting any component that creates a native OpenGL surface.

**Root cause:** SELinux enforces that sideloaded apps (`untrusted_app` context) cannot access `sysfs_kgsl` (the Qualcomm Adreno GPU sysfs interface):

```
avc: denied { search } for comm=RenderThread
  scontext=u:r:untrusted_app:s0
  tcontext=u:object_r:sysfs_kgsl:s0
  tclass=dir  permissive=0
```

When the GPU driver (kgsl) is denied its sysfs entry point, its internal initialisation corrupts memory — leading to the SIGSEGV in GPU memory (`0xa7xxxxxx`). The crash is **not triggered by touch gestures**; it happens as soon as the OpenGL surface is created and the driver starts.

This affects **any** component backed by a native GL surface, including:

| Component | What it creates | Status on Karoo |
|---|---|---|
| `react-native-webview` | SurfaceView (Chrome WebView) | Mount crashes GPU |
| `@maplibre/maplibre-react-native` | TextureView / SurfaceView | Render crashes GPU |
| `ActivityIndicator` | Native animated View | Crashes GPU |

The native Karoo system app is signed with Hammerhead's platform key, which grants it `platform_app` or `system_app` SELinux context — a context that IS allowed to access `sysfs_kgsl`. Third-party sideloaded apps cannot obtain this privilege without being re-signed by Hammerhead.

**Implementation — WebView:**

The Pyodide WebView is not mounted on Android < 29 (the same API level used as the proxy for "Chrome 61 / no WebAssembly.Global"). `_engineUnavailable` is set at module load time and `PyodideWebView` is conditionally excluded from the render tree:

```tsx
{Platform.OS !== 'android' || (Platform.Version as number) >= 29
  ? <View style={styles.hiddenEngine}><PyodideWebView /></View>
  : null}
```

**Implementation — MapLibre:**

`RouteMap` in `app/activity/[id].tsx` skips all MapLibre components on Android < 29 and renders a pure SVG route trace instead:

```typescript
if (Platform.OS === 'android' && (Platform.Version as number) < 29) {
  return <SvgRouteView geojson={geojson} accent={accent} />;
}
```

`SvgRouteView` extracts the GPS coordinates from the GeoJSON, applies an equirectangular projection with cosine correction for latitude, downsamples to ≤500 points, and renders the route as an SVG `Path` via `react-native-svg`. No native surface, no GPU access, no crash.

**Implementation — ActivityIndicator:**

`ActivityIndicator` is a native animated component that also creates GPU-backed layers. It is not used anywhere in the app. All loading states use plain `<Text>` with `…`.

---

### 3 — Server-side extraction fallback

When Pyodide cannot run (Android < 29 / Chrome 61), FIT/GPX/TCX files are extracted by the Bincio server instead of on-device.

**Server endpoint:** `POST /api/upload/raw`

Accepts JSON `{ filename: string, base64: string }`. The server decodes the file, runs the full Python extraction pipeline (including DEM correction), stores the result in the user's feed, and returns the extracted data:

```json
{
  "ok": true,
  "id": "2026-04-17T074238Z",
  "detail": { … },
  "timeseries": { … },
  "geojson": { … },
  "source_hash": "sha256:…"
}
```

**Client:** `extractFileViaServer()` in `mobile/extraction/extractServer.ts`. The Import screen routes to this function when `isEngineAvailable() === false`:

```typescript
if (isEngineAvailable() === false) {
  result = await extractFileViaServer(name, base64, instanceUrl, token, onStatus);
} else {
  result = await extractFile(name, base64, wheelBase64, wheelFilename, onStatus);
}
```

**Trade-offs vs. local extraction:**

| | Local (Pyodide) | Server-side |
|---|---|---|
| Requires internet | No (after wheel cached) | Yes |
| Requires Bincio account | No | Yes |
| File leaves device | Never | Yes (over HTTPS to your instance) |
| DEM correction | No | Yes |
| Supported on Karoo | No (Chrome 61) | Yes |

**Pre-flight auth check:** before starting a batch import via the server path, the Import screen calls `checkServerAuth()` which hits `GET /api/feed` to verify the token is still valid. If the token is expired, the error is shown immediately — not after processing hundreds of files.

**UI notice:** the Import screen shows an amber banner when running in server-extraction mode:

> ⚠ Your Android version doesn't support on-device extraction. Files will be processed by your Bincio instance.

---

## Android vs iOS: platform divergences

### Filesystem access

| | Android | iOS |
|---|---|---|
| App sandbox | App has its own private directory | App has its own private directory |
| External paths | Can read arbitrary paths on the filesystem with `READ_EXTERNAL_STORAGE` (≤ Android 12) or `READ_MEDIA_*` scoped permissions (Android 13+) | **Fully sandboxed.** No access to paths outside the app container or Files app |
| Karoo rides dir | `expo-file-system` can read `/sdcard/Karoo/Rides/` directly once permission is granted | Not possible |
| Manual import | Document picker or share sheet | Document picker or share sheet |

### Auto-import (Phase 2)

| | Android | iOS |
|---|---|---|
| Mechanism | Poll a configured directory path every few minutes via a background task | Not possible — iOS apps cannot read external directories |
| Background execution | `expo-background-fetch` fires reliably; Android allows longer background windows | Background fetch is capped at ~30 s and is not guaranteed to fire; effectively unavailable |
| Import trigger | Automatic on new FIT file detected in watched directory | Manual: user shares file via Files app or "Open with Bincio" |
| Karoo auto-import | ✅ Full support — configure path once, rides appear automatically | ✗ Not applicable (Karoo is Android) |

### Summary: what is Android-only

- Auto-import from a watched directory (Phase 2)
- `auto_import_path` setting (hidden in the UI on iOS)
- APK sideloading (for Karoo)

Everything else — extraction, local feed, activity detail, sync — is identical on
both platforms.

---

## Data model on device

```sql
CREATE TABLE activities (
  id              TEXT PRIMARY KEY,   -- BAS ID: "2026-04-17T074238Z"
  source_hash     TEXT NOT NULL,      -- SHA-256 of raw file (dedup key)
  detail_json     TEXT NOT NULL,      -- full BAS detail JSON blob
  timeseries_json TEXT,               -- 1 Hz arrays, loaded lazily
  geojson         TEXT,               -- simplified GPS track
  original_path   TEXT,               -- path in app storage (NULL if pulled from server)
  source_path     TEXT,               -- original filesystem path before copy
                                      -- e.g. /sdcard/Karoo/Rides/ride.fit
                                      -- used for watch-folder deduplication (migration v2)
  synced_at       INTEGER,            -- unix timestamp of last push (NULL = unsynced)
  origin          TEXT NOT NULL       -- "local" | "remote"
    CHECK(origin IN ('local', 'remote')),
  created_at      INTEGER NOT NULL DEFAULT (unixepoch())
);

CREATE TABLE settings (
  key   TEXT PRIMARY KEY,
  value TEXT NOT NULL
);
```

**Settings keys:**

| Key | Description | Platform |
|---|---|---|
| `instance_url` | e.g. `https://bincio.org` | Both |
| `handle` | User's handle on the remote instance | Both |
| `api_token` | Bearer token for API auth (obtained via Connect, never stored in plaintext long-term) | Both |
| `sync_mode` | `"summaries"` (default) or `"full"` — controls whether geojson+timeseries are downloaded during sync | Both |
| `sync_upload` | `"true"` or `"false"` — whether to push local activities during sync | Both |
| `upload_format` | `"raw"` (default) or `"bas"` — whether to upload the original FIT/GPX/TCX file (server re-extracts with DEM) or the pre-extracted JSON | Both |
| `auto_import_path` | Directory to watch for new FIT files | **Android only** |

---

## Sync protocol

### Download (server → local)

Implemented in `mobile/db/sync.ts` → `syncFeed()`.

1. `GET {instance_url}/api/feed` with `Authorization: Bearer <token>` — returns all
   activity summaries as `{ activities: [...] }`.
2. Upsert each summary into the local `activities` table with `origin = 'remote'`.
   Returns `changes > 0` (new or updated) per row; counts synced entries.
3. **Summaries mode** (default): stops here. Geojson and timeseries are fetched
   on-demand when the user opens an activity detail screen.
4. **Full mode**: for every activity where `geojson` or `timeseries_json` is NULL,
   fetches `GET /api/activity/{id}/geojson` and `GET /api/activity/{id}/timeseries`.
   Uses `COALESCE` in the UPDATE to avoid overwriting already-stored data.

### Upload (local → server)

Implemented in `mobile/db/sync.ts` → `uploadFeed()` / `uploadLocalActivities()`. Enabled when
`sync_upload = "true"` in settings, or triggered explicitly via the ↑ Upload button.

1. **Reconcile** against the server: fetch `GET /api/feed` and compare its activity IDs against local rows where `synced_at IS NOT NULL`. Any local activity that is marked as synced but absent from the server (e.g. server was wiped) has its `synced_at` cleared so it re-enters the upload queue. This is best-effort — if the feed fetch fails, upload proceeds with whatever is currently queued.
2. Query `activities WHERE origin = 'local' AND synced_at IS NULL`.
3. For each, choose the upload path based on the `upload_format` setting (default `'raw'`):
   - **`raw` (default):** if `original_path` is set and the file still exists on disk, read it as base64 and `POST {instance_url}/api/upload/raw { filename, base64 }`. The server re-extracts the file with DEM elevation correction and returns `{ id, detail, timeseries, geojson, source_hash }`. After a successful upload, the local row's `detail_json`, `timeseries_json`, `geojson`, and `source_hash` are updated with the server's better data (Option A). Falls back to `bas` if the file is missing.
   - **`bas`:** `POST {instance_url}/api/upload/bas { activity, timeseries?, geojson? }` with the pre-extracted JSON from the DB. Faster, but no DEM elevation correction.
4. On 200 (including `{ status: "duplicate" }`): set `synced_at = unixepoch()`. On error: log to console, count as failed, continue with next activity.

The UI shows live progress ("Uploading N / M…") during the batch and reports failures separately ("X uploaded, Y failed").

**Upload format setting (`upload_format`):** controls whether to prefer the original raw file or the pre-extracted JSON. `raw` is the default and is recommended — it produces DEM-corrected elevation data on the server and back-fills the local copy. Switching between modes is safe: the server deduplicates by activity id, so switching from `raw` to `bas` just results in the server returning `{ status: "duplicate" }` (HTTP 200) and the client marking the activity as synced.

**Server endpoint for BAS JSON** (`POST /api/upload/bas`): accepts pre-extracted BAS JSON, writes the activity file, updates `user_dir/index.json` with a summary entry (so `merge_all` can include the activity in year shards and the browser feed), writes geojson and timeseries if provided, then calls `merge_all()` + `write_combined_feed()`.

**Server endpoint for raw files** (`POST /api/upload/raw`): accepts a base64-encoded FIT/GPX/TCX file, runs full server-side extraction with DEM correction, stores the result, updates the index, calls `merge_all()` + `write_combined_feed()`, and returns the full extracted data to the client.

> **Bug that was fixed:** earlier versions of both `/api/upload/bas` and `/api/upload/raw`
> wrote activity files to disk but never updated `user_dir/index.json`. Since `merge_all`
> builds year shards from the index, uploaded activities existed on disk but were invisible
> to the browser feed. Fixed by `_upsert_index_summary()` called before `merge_all()`.

### Conflict handling

Activities are immutable. Dedup on download: `ON CONFLICT(id) DO UPDATE` only
updates `detail_json` and `synced_at`. Dedup on upload: the server returns
`{ ok: true, status: "duplicate" }` (still HTTP 200) if the file already exists.

---

## Authentication

The server exposes `POST /api/auth/token`:

```
POST /api/auth/token
Body: { "handle": "…", "password": "…" }
→    { "token": "abc123…", "display_name": "…" }
```

The token is stored in the `settings` table as `api_token` and sent as
`Authorization: Bearer abc123…` on all sync requests. The password is used once and
immediately discarded — it is never persisted.

The server's `_require_auth` helper accepts both cookie-based session auth (web) and
Bearer token auth (mobile), so no separate mobile-specific middleware is needed.

---

## Mobile API endpoints

All endpoints require `Authorization: Bearer <token>` from the mobile client.

| Method | Path | Description |
|---|---|---|
| `POST` | `/api/auth/token` | Password login → Bearer token |
| `GET` | `/api/feed` | All activity summaries for the authenticated user |
| `GET` | `/api/activity/{id}/geojson` | GeoJSON route for one activity |
| `GET` | `/api/activity/{id}/timeseries` | Timeseries JSON for one activity |
| `POST` | `/api/upload/bas` | Upload a pre-extracted BAS JSON activity (body: `{ activity, timeseries?, geojson? }`) |
| `POST` | `/api/upload/raw` | Upload a raw FIT/GPX/TCX file for server-side extraction (body: `{ filename, base64 }`); returns full extracted data |
| `GET` | `/api/wheel/version` | Latest bincio wheel version + URL (public) |
| `GET` | `/api/wheel/download` | Serve the wheel file (dev mode fallback) |

---

## Implementation plan

### Phase 0 — Foundation ✅
*Goal: app launches, settings can be configured, a BAS JSON file can be picked
and displayed as an activity card. No extraction yet.*

- Expo Router with three tabs: **Feed**, **Import**, **Settings**
- `expo-sqlite` initialised; `activities` and `settings` tables created on first launch
- Settings screen: instance URL and handle, saved to `settings` table
- Import screen: `expo-document-picker`; BAS `.json` files parsed and inserted into feed
- Feed screen: activity cards sorted by `started_at`, sport icon, distance, elevation
- `GET /api/wheel/version` server endpoint (public, no auth)

**Done when:** App launches, user picks a `.json` BAS file, sees it in the Feed. ✅

---

### Phase 0.5 — Remote feed sync ✅
*Goal: pull all activities from a remote bincio instance into the local feed.*

- `POST /api/auth/token` — password login returning a Bearer token (stored in
  SQLite; password forgotten immediately after)
- `GET /api/feed` — auth-gated; reads `_merged/index.json` shards and returns
  all activity summaries as JSON
- Settings screen: Connect section (password field + Connect button + status);
  Disconnect button clears the stored token
- Feed screen: three header buttons — **↑ Upload**, **↓ Download**, **↺ Refresh**;
  pull-to-refresh; "cloud" badge on remote activities
  - **↓ Download** calls `downloadFeed()` — pulls summaries (and full data in full mode)
  - **↑ Upload** calls `uploadFeed()` — pushes unsynced local activities to the server
  - **↺ Refresh** and pull-to-refresh: local-only SQLite re-read, no network call
  - Auto-refresh on tab focus via `useFocusEffect`: increments `refreshKey` → FlatList
    picks up newly imported activities without any user action

**Done when:** Tap Connect, tap ↓ Download, all instance activities appear in the Feed. ✅

---

### Phase 4 — Activity detail: map + metric charts ✅
*Goal: every activity shows a route map and metric charts.*

> Phase 4 was implemented before Phase 1 because it only requires the Development
> Build already needed for MapLibre — no Pyodide work required.

**Map (MapLibre v11 — modern Android and iOS):**
- Dark CartoDB tile base map via `mapStyle` prop
- Route drawn as a GeoJSON `LineLayer` (`line-color: #60a5fa`, `line-width: 3`)
- Camera auto-fits the track bounding box via `initialViewState.bounds`
- Thumbnail (non-interactive) shown inline; tap **⤢ tap to explore** to open a
  full-screen modal with pan/zoom/pitch/rotate enabled
- Full-screen modal: **+/−** zoom buttons (bottom-right corner) adjust zoom level
  via `cameraRef.current?.setCamera({ zoomLevel: … })`. Current zoom tracked via
  `onRegionDidChange`.
- On-demand fetch for remote activities: `GET /api/activity/{id}/geojson` with
  Bearer auth; result cached in memory for the session

**Map (SVG route trace — Android < 29 / Karoo):**
- MapLibre is not rendered on Android < 29 — doing so crashes the GPU driver (see
  *Karoo 2: hardware and OS constraints* above).
- `SvgRouteView` in `app/activity/[id].tsx` renders an SVG path using `react-native-svg`.
  Coordinates are projected via equirectangular projection with cosine correction for
  latitude, downsampled to ≤500 points. No native OpenGL surface is created.
- The visual is identical to what a GPS watch shows: the route shape as a coloured
  trace on a dark background, without map tiles. No zoom is provided (no native
  interaction surface, no crashes).

**Metric charts (react-native-svg):**
- Tabbed interface: Elevation / Speed / HR / Cadence / Power
- Only tabs with non-null data are shown
- Each chart: SVG area chart with gradient fill and coloured stroke; min/max labels
- Downsampled to ≤300 points for performance
- Tab colours: elevation `#00c8ff`, speed `#ff6b35`, HR `#f87171`, cadence `#a78bfa`, power `#facc15`
- On-demand fetch for remote activities: `GET /api/activity/{id}/timeseries`

**Stats grid:** distance, moving time, elevation gain/loss, avg speed, avg HR, avg power.

**Done when:** Open any synced or locally imported activity — map and charts visible. ✅

---

### Phase 0.6 — Sync mode + bidirectional sync ✅
*Goal: control download depth and push local activities back to the server.*

> Implemented as an addition to Phase 0.5 sync, ahead of Phase 1.

**Download mode (Settings → Sync → Download):**
- **Summaries only** (default): sync downloads activity summaries only. Map and
  charts are fetched on first open.
- **Full data**: sync downloads geojson and timeseries for every activity that is
  missing them. Uses more storage; takes longer.

**Upload (Settings → Sync → Upload):**
- **Off** (default): local activities stay on device only.
- **Upload local activities**: during each sync, unsynced local activities are
  POSTed to `POST /api/upload/bas` as pre-extracted BAS JSON (not original FIT).
  The server deduplicates, writes the files, and re-merges the feed.

**Settings → Data:**
- **Reset synced data**: two-tap confirm button to delete all remote activities from
  the local DB. Useful when switching instances or re-syncing from scratch.

**Feed sync message** shows counts: `Synced: 3 new, 2 full datasets, 1 uploaded (47 total)`.

**Done when:** Sync pushes local activities to the instance and reports them in the feed. ✅

---

### Phase 1 — Local FIT/GPX/TCX extraction via Pyodide ✅
*Goal: pick a FIT/GPX/TCX file, extract it on-device in ~5 s.*

**Extraction engine (`mobile/extraction/`):**
- `PyodideWebView.tsx` — hidden `WebView` (mounted in the Import tab) rendering
  an inline HTML page that bootstraps Pyodide from jsDelivr CDN. The WebView is
  kept alive between files because Expo Router keeps tabs mounted after first visit.
- `extractActivity.ts` — module-level singleton `pyodideRef`; encodes file bytes
  as base64, injects `window._bincioExtract(params)` into the WebView, awaits
  `{ id, detail, timeseries, geojson, sourceHash }` via `onMessage`. Serial queue
  enforced via `isExtracting` guard — only one extraction runs at a time.

**Wheel delivery:**
- The bincio wheel is fetched by React Native networking (not inside the WebView),
  because WKWebView on iOS blocks HTTP requests. `GET /api/wheel/version` returns
  the canonical URL; the wheel bytes are passed into the WebView as base64 and
  installed via `emfs://` (blob: URLs are not recognised by micropip).
- In-memory wheel cache (`_cachedWheel`) avoids re-downloading within a session.

**Import screen:**
- Picks one or more FIT/GPX/TCX/.json files; processes them sequentially.
- Copies original file to `{documentDirectory}/originals/{id}.{ext}`.
- Stores `detail_json`, `timeseries_json`, `geojson`, `source_hash`, `source_path`
  in SQLite.

**Known bug in wheel (worked around):**
`write_activity()` in the installed wheel silently skips writing the timeseries
file (an uncaught exception path). The extraction snippet checks `ts_path.exists()`
after `write_activity()` and, if missing, calls `build_timeseries()` directly and
writes the file itself. Without this fix, all locally imported activities showed
stats but no elevation chart or speed graph.

**Done when:** Pick a FIT file from the Karoo rides folder, see full stats in
the Feed, including map and elevation profile. ✅

---

### Phase 2 — Karoo auto-import *(Android only)*
*Goal: finish a ride, open the app, activities appear automatically.*

> **Partially implemented.** The watch-folder scan runs on Import tab mount and
> on every app foreground event, which covers the primary Karoo use case (open the
> app after a ride). True background polling (fires while the app is closed) is not
> yet implemented — that would require `expo-background-fetch` + `expo-task-manager`,
> but background tasks cannot access the Pyodide WebView (a UI component), so this
> requires a different architectural approach for the extraction step.

**What's implemented:**
- `auto_import_path` setting in Settings (Android only) ✅
- On Import tab mount and on `AppState` → `'active'`: reads `auto_import_path`,
  requests `READ_EXTERNAL_STORAGE` permission, lists `.fit` files in the directory,
  filters out files whose `source_path` is already in the DB, and automatically
  imports new files through the same Pyodide extraction pipeline.
- New `source_path` column in `activities` (migration v2): stores the original
  filesystem path (`/sdcard/Karoo/Rides/ride.fit`) for O(1) deduplication without
  re-reading files.
- Batch import: picks multiple files at once (`multiple: true`), processes them
  sequentially, shows "File N of M" progress, ends with a count + per-file errors.

**iOS (alternative flow):**
- Share Extension config so "Open with Bincio" appears in the iOS Files app
- Tapping it hands the file to the app, which runs extraction immediately
- No background polling; user-initiated but one-tap

**Done when (Karoo):** Finish a ride, open the Bincio app → new FIT files from
`/sdcard/Karoo/Rides` import automatically with no further action. ✅ (on-open)

**Remaining (background):** true background polling while app is closed — deferred.

---

### Phase 3 — Push sync (original files)
*Goal: upload original FIT/GPX/TCX files to the server for server-side re-extraction.*

Phase 0.6 already pushes **pre-extracted BAS JSON** to the server, which covers
the common case. Phase 3 adds upload of the **original raw file** so the server
can re-extract with its full pipeline (DEM correction, hysteresis, etc.).

**Server:**
- Extend `POST /api/upload` to accept raw FIT/GPX/TCX with Bearer token auth
  (currently cookie-only)

**App:**
- When `original_path` is set, prefer uploading the raw file; fall back to BAS JSON
- Progress indicator per activity for first push with many files

**Done when:** Tap **Sync**, locally imported FIT files are uploaded to the instance
and re-extracted server-side.

---

### Phase 5 — Polish *(ongoing)*

- **Offline map tiles** — bundle or download an MBTiles file for a region;
  MapLibre supports offline tile sources
- **Batch import** ✅ — `multiple: true` in document picker; sequential processing with "File N of M" progress and per-file error summary
- **Share sheet** — Android intent filter for incoming `.fit`/`.gpx`/`.tcx` files
- **Re-extract** — button to re-run Pyodide extraction from the stored original file
  *(requires Phase 1)*
- **App icon and splash screen** — currently using Expo defaults
- **Feed search / filter** — by sport, date range, or title; necessary as the
  feed grows past ~50 activities
- **Individual activity deletion** — currently users can only "Reset synced data"
  (all remote) or nothing (local). No way to delete a single activity.
- **Token expiry / reconnect prompt** — when the server returns 401, the app shows
  an error in the sync toast but leaves the user to navigate to Settings manually.
  Should auto-show a reconnect prompt instead.

---

## Known gaps and technical debt

This section documents mismatches between what the plan describes and what is
actually implemented, plus features not yet in the plan.

### Remaining stubs

**`source_hash` for BAS JSON import is not SHA-256** (`mobile/app/(tabs)/import.tsx`)

BAS JSON import records `source_hash = "${detail.id}-${text.length}"` — a rough
stand-in. FIT/GPX/TCX imports (via Pyodide) correctly compute SHA-256 of the file
bytes. The BAS JSON path still uses the stub; dedup works in practice (activity IDs
are unique) but the hash is not a real content fingerprint.

**`auto_import_path` only triggers on app open, not in background**

The watch-folder scan runs when the Import tab mounts and when the app comes to
foreground (`AppState` → `'active'`). There is no true background task that fires
while the app is closed. Full background polling would require `expo-background-fetch`
but cannot use the Pyodide WebView (a UI component).

### Missing from the plan entirely

**Feed pagination**

`useActivities()` in `mobile/db/queries.ts` calls `getAllSync` with no `LIMIT`.
This is fine for tens of activities, but will cause noticeable lag at hundreds.
Should add cursor-based pagination or a virtual list with lazy loading.

**Individual activity deletion**

There is no way to delete a single activity, local or remote. "Reset synced data"
nukes all remote activities at once. A long-press or swipe-to-delete gesture on
activity cards is needed, with a server-side `DELETE /api/activity/{id}` endpoint
for remote activities.

**Feed search and filter**

No search bar, no sport filter, no date picker. The feed is a flat reverse-
chronological list. As the feed grows this becomes a usability problem.

**Token expiry and the reconnect flow**

Bearer tokens are stored indefinitely and never refreshed. When the server rejects
one (HTTP 401 during sync), the error toast says "Session expired — reconnect in
Settings." The user must navigate there manually. A better flow: on 401, show a
modal with a password field so the user can reconnect inline without leaving the
sync flow.

**App icon and splash screen**

The app uses Expo's default purple icon and white splash. These need to be replaced
with Bincio branding before any public distribution.

**Upload only pushes `origin = 'local'` activities**

`uploadLocalActivities()` queries `WHERE origin = 'local' AND synced_at IS NULL`.
Activities pulled from the server (`origin = 'remote'`) are never re-uploaded — correct
behaviour. A locally created activity from a future recording feature that lacks
`detail_json` would throw during `JSON.parse` and be silently skipped; worth checking
if a recording path is ever added.

---

## Out of scope for v1

- **Live activity recording** — GPS track + sensor data during a ride. This is the
  eventual goal for complete platform independence but requires significant additional
  work (background GPS, Bluetooth/ANT+ sensor integration, real-time display).
- **Editing activities** — read-only in v1; edits happen via the web interface.
- **Photo sync** — deferred.

---

## Future: toward full platform independence

Once live recording is implemented, the stack becomes:

```
Ride starts  →  Bincio records GPS + sensors (BLE power meter, HR strap, etc.)
Ride ends    →  Bincio extracts the activity locally (Pyodide or native)
              →  Activity visible in the mobile feed immediately
              →  Original FIT file saved on device
              →  Optional: push to bincio.org for web access
```

At that point Garmin Connect, Hammerhead sync, and Strava become entirely optional.
The Karoo (or any Android head unit running the app) becomes a self-contained
training ecosystem.