Davide Scaini
13 KiB
Bincio Mobile App — Design Document
Vision
The long-term goal is full independence from Garmin Connect, Strava, 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.
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 (bincio.org or self-hosted) adds cloud backup, the web feed, and the ability to share activities. 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.
What already exists
Several pieces of the mobile app are already implemented or proven:
| 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 running in the browser. This is the proof of concept for mobile extraction — a hidden WebView in the app uses the exact same mechanism. |
| Bincio wheel | served at /bincio-0.1.0-py3-none-any.whl |
The extraction code packaged as a pure-Python wheel. Already downloaded and run by the /convert/ page. |
| Local activity storage | site/src/pages/convert/ |
IndexedDB + service worker in the web app. Proves the concept; the mobile app uses SQLite instead. |
| Content-addressed dedup | bincio/extract/dedup.py |
source_hash (SHA-256 of raw file) prevents duplicates on upload |
| Sync-ready REST API | bincio/serve/server.py |
Login, upload, activity detail, index.json — the sync primitives are already there |
| Settings persistence | bincio/serve/db.py |
settings table (key/value) for instance URL, auth token, sync preferences |
Technology choice
Cross-platform framework: Expo (React Native)
Expo (React Native + the Expo SDK) is the recommended platform:
- TypeScript-first, large ecosystem
expo-sqlite(v2+) — fast on-device SQLite with WAL mode- File picking from device storage:
expo-document-picker - Direct filesystem access (critical for Karoo):
expo-file-system - Maps: MapLibre React Native (
@maplibre/maplibre-react-native) — same tile standard as the web app, self-hostable - Background tasks:
expo-background-fetch/expo-task-manager - Expo Go for rapid development without a build step
- EAS Build for iOS and Android distribution
Why not alternatives:
| Option | Reason for skipping |
|---|---|
| Capacitor + Svelte | WebView performance is poor for map-heavy activity detail; same hidden-WebView trick for Pyodide applies either way |
| Flutter | Dart is a new language; no practical advantage for this use case |
| PWA | iOS limits background sync, local storage quotas, and filesystem access — not viable for an activity logger |
Extraction: Pyodide in a hidden WebView
This is the core technical insight. The /convert/ page already demonstrates that
the full Python extraction pipeline can run in a browser via Pyodide (CPython
compiled to WebAssembly). A React Native app can host a hidden WebView component
running the exact same code. No rewrite required.
How the /convert/ page does it today
Browser tab
└── Pyodide (CPython → WASM, ~30 MB)
├── lxml (pre-compiled in Pyodide — XML/GPX parsing)
├── fitdecode (pure Python — FIT parsing)
├── gpxpy (pure Python — GPX parsing)
├── pyyaml (pure Python)
└── bincio wheel (pure Python — metrics, hysteresis, writers)
fetched from: /bincio-0.1.0-py3-none-any.whl
All dependencies are either pre-compiled in Pyodide or pure Python with no C extensions. This is the key: there is nothing to recompile for mobile.
How the mobile app does it
React Native app
└── Hidden WebView (WKWebView on iOS, Chrome WebView on Android)
└── Same Pyodide environment as the /convert/ page
├── Pyodide runtime (cached on device after first download)
├── lxml, fitdecode, gpxpy, pyyaml (cached)
└── bincio wheel (fetched from bincio.org on startup / version check)
Data flow:
1. App reads FIT file bytes from device filesystem
2. Sends bytes to WebView via postMessage
3. WebView writes bytes to Pyodide's virtual FS
4. Python runs the extraction → BAS JSON dict
5. WebView sends JSON back via postMessage
6. App stores BAS JSON in SQLite, original file on disk
Data never leaves the device. The only network traffic is:
- Pyodide runtime (CDN or bundled, ~30 MB, cached)
- Common packages (CDN or bundled, cached)
- The bincio wheel from bincio.org (~50 KB, updated on version bump)
Algorithm updates without app store releases
The bincio wheel is versioned and served from bincio.org. On app startup (or periodically), the app checks the current wheel version:
GET https://bincio.org/bincio-latest.whl (or a version manifest endpoint)
If a new version is available, the wheel is downloaded and cached. The next extraction uses the updated algorithm. Improvements to hysteresis thresholds, DEM correction, lap detection, or any other metric are live on all devices within hours of deployment — no App Store submission required.
Performance
- First extraction after install: ~5–8 s (Pyodide startup + package load)
- Subsequent extractions (warm WebView): ~1–3 s per activity
- Pyodide memory footprint: ~100–150 MB RAM while active; the WebView can be suspended between extractions
- Wheel size: the bincio extract code is ~50 KB; Pyodide + packages ~30 MB (downloaded once, cached on device)
For batch import (many files at once), the WebView is kept warm across extractions, making the per-file cost just the Python execution time (~0.5–1 s per typical activity).
Architecture
Bincio Mobile
├── UI Layer (React Native / Expo)
│ ├── Feed screen — list of local activities, sorted by date
│ ├── Activity detail — map + elevation chart + stats
│ ├── Import screen — pick FIT/GPX/TCX from device or share sheet
│ ├── Sync screen — configure instance URL, push/pull
│ └── Settings screen — account, preferences, storage info
│
├── Extraction Engine (Pyodide in hidden WebView)
│ ├── WebView host — manages lifecycle, message passing
│ ├── Wheel cache — versioned bincio wheel stored on device
│ └── Python runtime — Pyodide + fitdecode + gpxpy + lxml
│ identical to the /convert/ page on the web
│
├── Local Store (expo-sqlite)
│ ├── activities — BAS detail JSON + indexed summary columns
│ ├── timeseries — 1 Hz arrays as JSON blob per activity
│ ├── geojson — simplified GPS track per activity
│ ├── originals — original file paths per activity
│ └── settings — instance_url, handle, auth_token, sync prefs
│
└── Sync Layer (optional)
├── Auth — POST /api/auth/login → Bearer token
├── Push — POST /api/upload (original file)
└── Pull — GET index.json + activity/{id}.json + timeseries
Data model on device
-- activities table
id TEXT PRIMARY KEY, -- BAS ID: "2026-04-17T074238Z"
source_hash TEXT NOT NULL, -- SHA-256 of original 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 NOT NULL, -- path to original file in app storage
synced_at INTEGER, -- unix timestamp of last push to remote
origin TEXT NOT NULL, -- "local" | "remote"
created_at INTEGER NOT NULL
-- settings table
key TEXT PRIMARY KEY,
value TEXT NOT NULL
Settings keys:
| Key | Example value |
|---|---|
instance_url |
https://bincio.org |
handle |
brutsalvadi |
session_token |
abc123… |
last_sync_at |
2026-04-24T10:00:00Z |
wheel_version |
0.1.0 |
auto_import_path |
/sdcard/Karoo/Rides/ (Android only) |
Karoo and Android-first devices
Devices like the Karoo 2 run Android and write FIT files directly to the
filesystem (e.g. /sdcard/Karoo/Rides/). The app can monitor this directory and
auto-import new files as rides complete — no manual export step, no Hammerhead
cloud sync, no Garmin Connect, no Strava required.
On Karoo specifically:
- Install the Bincio Android APK directly (sideload or via a store).
- Configure
auto_import_pathto point at the Karoo's ride directory. - When a new FIT file appears, the app imports it automatically (Pyodide extraction), stores the original file, and shows the ride in the feed.
- When WiFi is available and an instance is configured, rides can be pushed to the instance for web access and backup.
This makes Bincio a complete replacement for Hammerhead's own sync infrastructure for users who want full control of their data.
Sync protocol
Sync is a two-way, hash-based diff — no custom server protocol needed.
Push (local → server)
- Fetch
{instance_url}/{handle}/index.jsonto get remote activity IDs. - Find local activities where
synced_at IS NULL. - For each unsynced activity,
POST /api/uploadwith the original file. - On 200, set
synced_at = now().
Pull (server → local)
- Fetch
{instance_url}/{handle}/index.json(and yearly shards). - Find remote IDs not in the local DB.
- For each missing activity:
GET {instance_url}/activities/{id}.json→detail_jsonGET {instance_url}/activities/{id}.timeseries.json→timeseries_jsonGET {instance_url}/activities/{id}.geojson→geojson
- Insert with
origin = "remote",synced_at = now().
Note: pulled activities don't have a local original file. If re-extraction is needed (e.g. for a DEM correction), the original must be uploaded to the instance first so the server can serve it back.
Conflict handling
Activities are immutable once created. The source_hash prevents double-counting:
if the same file is imported on two devices before sync, whichever arrives at the
server first wins; the duplicate is rejected with 409.
Authentication
The multi-user server currently uses HTTP session cookies. For the mobile client, a Bearer token is cleaner:
POST /api/auth/token
{ "handle": "…", "password": "…" }
→ { "token": "abc123…", "expires_at": "…" }
The token is stored in the settings table and sent as
Authorization: Bearer abc123… on all subsequent requests.
What is out of scope for v1
- Live activity recording — GPS + sensor recording during a ride. This is a much harder problem (background GPS, Bluetooth/ANT+ sensors, real-time display) and is the eventual goal for full platform independence.
- Offline map tiles — v1 requires network for map rendering.
- Photo sync — deferred.
- Watch / ANT+ / Bluetooth sensors — deferred.
- Editing activities on mobile — read-only in v1; edits happen on the web.
Roadmap
| Phase | Scope |
|---|---|
| 0 — Foundation | Expo project scaffold, SQLite store, settings screen, file picker, display a BAS JSON read from disk |
| 1 — Import | Hidden WebView + Pyodide extraction, wheel download and caching, local feed, activity detail with map and chart, original file storage |
| 2 — Karoo integration | Auto-import from a watched directory, Android-specific filesystem access |
| 3 — Sync | Bearer token auth, push/pull sync with a Bincio instance |
| 4 — Polish | Offline map tiles, share sheet, home screen widget, batch import performance |
| Future | Live recording, Bluetooth/ANT+ sensors, full Garmin/Wahoo/Hammerhead replacement |