samplez/rippr-src/docs/port/PLAN.md

# Rippr — Flutter Port (Android + iOS)

## Context

Rippr is a native Android GPS ride recorder: ~3,800 lines of Kotlin across 34 files,
shipped through v1 and v2.0.1, validated on real rides. It records telemetry from a
foreground service into Room, renders the path on osmdroid, and exports GPX/GeoJSON.

Dylan wants one codebase running on **both iOS and Android** before any further features
are built. This is a **full rewrite in Flutter**, not an incremental or add-to-app
migration — the research in `docs/PORT_RESEARCH.md` puts the cutover threshold at 10
screens and Rippr has **six**, with no legacy debt worth preserving in Kotlin form.

**The goal is parity, not improvement.** Every capability in the v2.0.1 feature table
works on both platforms; v3 features stay in the backlog. Deliberate scope discipline —
the port is finished when it does exactly what the Kotlin app does.

### Three findings that shape this plan

**The pure-logic core ports almost verbatim.** Eight files (~890 lines) carry zero Android
imports — a discipline held deliberately since v1. `Geo`, `RideStatistics`,
`RideAccumulator`, `RideExport`, `Telemetry`, `Format`, `LiveTelemetry`, `UploadStatus`.
Their ~965 lines of existing JVM tests become a **differential oracle**: the same fixtures
must produce the same numbers in Dart. This is the single biggest de-risker available and
Phase 1 exists to cash it in first.

**Whoever owns the writes must own the database.** `TrackingService` writes to Room
directly from its writer loop. If Dart owns the schema but a native service owns the
writes, every fix crosses a platform channel that is *dead while iOS suspends Dart*. So
Dart owns both, and the background layer only has to keep the Dart isolate alive.

**iOS suspends a stationary app; Android does not.** This is the one place where "write
once" is partly an illusion, and it gets its own task and its own real-world validation
rather than being discovered late.

### Decisions taken

| Decision | Choice | Rationale |
|---|---|---|
| Strategy | **Full rewrite** | 6 screens, well below the 10-screen threshold |
| Repo | **`~/dojo/rippr-flutter`**, new git history | Native app stays installable as reference and fallback |
| Existing rides | **Start fresh** | No importer; export to GPX first if any ride matters |
| Location engine | **`geolocator` + `flutter_foreground_task`** | MIT/free; avoids the ~$500/yr Transistor licence |
| Isolate model | **Single isolate** | Foreground service for process liveness only — no second isolate, no cross-isolate SQLite |
| Database | **Drift** | Type-safe, streams, real migrations, runs on the Dart VM |
| State | **Riverpod** | Maps cleanly from ViewModel + StateFlow |
| Routing | **go_router** | Three destinations, same shape as navigation-compose |
| Map | **flutter_map** | OSM raster tiles, no API key — same reasoning that chose osmdroid |
| Live map while recording | **Still no** | Parity target is v2.0.1; it is a v3 decision |

### Non-goals

Every v3 backlog item: live map, waypointing, activity type, accounts, cloud backup,
theming overhaul, group ride. Also no new features of any kind, and no data importer.

---

## Architecture mapping

```
TrackingService (Kotlin)                RecordingEngine (Dart, main isolate)
  FusedLocationProviderClient    ──►      geolocator.getPositionStream
  Channel<TrackPoint>(UNLIMITED) ──►      StreamController (unbounded)
  single writer coroutine        ──►      single async drain loop (batch 25 / 2s)
  Mutex                          ──►      package:synchronized Lock
  Room + @Transaction            ──►      Drift + transaction()
  Flow<Trip?>                    ──►      Stream<Trip?> (Drift .watch)
  PARTIAL_WAKE_LOCK              ──►      flutter_foreground_task (Android)
  START_STICKY + adopt active    ──►      on-launch adopt of `endedAt IS NULL`

ViewModel + StateFlow            ──►      Riverpod Notifier / AsyncNotifier
navigation-compose               ──►      go_router
osmdroid MapView                 ──►      flutter_map
FileProvider + ACTION_SEND       ──►      share_plus
SharedPreferences                ──►      shared_preferences
OkHttp                           ──►      package:http
```

**Platform-divergent, by necessity:** Android runs a foreground service with a persistent
notification to keep the process alive. iOS declares `UIBackgroundModes: location` and
sets `allowsBackgroundLocationUpdates` with `pauseLocationUpdatesAutomatically = false`.
Both keep the *same* Dart pipeline running; only the liveness mechanism differs.

**Invariants carried over verbatim** (from `docs/v3/BACKLOG.md` §6 — each has a comment in
the Kotlin explaining why, and each must survive the port):

1. The location callback never blocks on disk — unbounded buffer, single batched writer
2. Points stamped with `tripId`/`segmentId` **at creation**, never looked up at write time
3. Recording state derived from the database, never an in-memory flag
4. No destructive migration — Drift migrations from v1 of the Dart schema onward
5. Decimation is render-only, never reaching storage or export
6. Theme sets a default content colour (Kotlin's `Surface` lesson; Dart's is `DefaultTextStyle`)
7. The map zoom clamp — a short ride must not zoom past the tile server's max
8. Tests use in-memory databases

---

## Phases and tasks

Each task gets `docs/port/NN-slug.md` in the new repo, following the v2 template that
worked well: Goal · Context · Design · Implementation · Acceptance criteria · Tests ·
Risks · Out of scope. Plus a running `docs/port/PROGRESS.md` recording what actually went
wrong — the v2 feedback loop caught real bugs and is worth repeating.

### Phase 0 — Ground clearing *(blocking; nothing else can start)*

| # | Task | Depends |
|---|---|---|
| T00 | Disk space + toolchain | — |
| T01 | Repo scaffold | T00 |

**T00 — This is a genuine blocker, not a formality.** The machine has **16 GiB free at 92%
capacity** and needs, roughly: Flutter SDK + artifacts ~5 GB, an iOS simulator runtime
(**none installed**) ~9 GB, CocoaPods (**not installed**; system Ruby is 2.6.10, so install
via Homebrew, not `gem`), plus the Android emulator's non-negotiable **7.4 GB free-space
floor** and two build trees. That does not fit — v1 hit this same wall and lost real time
to it. Reclaim first (`brew cleanup -s`, Homebrew and Playwright caches, `pip cache purge`,
`go clean -cache`, old Gradle caches, stale AVDs), then install. Xcode 26.0.1 is present.
**Exit criteria:** `flutter doctor -v` clean for both toolchains, an iOS simulator *and*
the Android emulator each boot, and ≥15 GB still free afterwards.

**T01** — `flutter create` with both platforms, bundle/application id `com.rippr`, git
init, initial commit. Add the dependency set. Write `docs/port/` scaffolding and a
`README` pointing back at the native repo's `ARCHITECTURE.md`, `TESTING.md`, and v2
`PROGRESS.md` as the source of truth for *why* things are shaped as they are. Confirm
`flutter test` and a debug build on both platforms before a line of real code.

### Phase 1 — Pure logic *(no platform, no UI, no database)*

Highest value per unit risk, and it builds Dart fluency on code whose correct answers are
already known. Each task ports the Kotlin file **and its existing test suite**.

| # | Task | Ports | Depends |
|---|---|---|---|
| T02 | Geo utilities | `geo/Geo.kt` + `GeoTest` (165 + 210 ln) | T01 |
| T03 | Telemetry + formatting | `Telemetry.kt`, `ui/Format.kt`, `UploadStatus.kt` + `TelemetryTest` | T01 |
| T04 | Ride statistics | `stats/RideStatistics.kt` + `RideStatisticsTest` (302 + 265 ln) | T02, T03 |
| T05 | Live accumulator | `RideAccumulator.kt`, `LiveTelemetry.kt` + `AccumulatorTest` | T04 |
| T06 | Export writers | `export/RideExport.kt` + `RideExportTest` (151 + 211 ln) | T02 |
| T07 | Cross-language parity harness | — | T02–T06 |

**T04 is the hardest-won code in the project.** `ElevationAccumulator` — 15-sample moving
average, reversal hysteresis, `gainIncludingPending()`, and a `finish()` that reconciles
against `lastRaw`. A naive version once reported **1498 m of climbing over a parked bike**.
Port it structurally faithfully; do not "improve" it during translation.

**T07** — Drive identical fixtures through both implementations and assert agreement to
six decimal places: haversine over known pairs, Douglas–Peucker output, elevation gain over
the noisy-stationary fixture, batched-vs-single-batch distance, GPX/GeoJSON byte output.
**Watch for a harness that reports suspiciously identical results** — a v2 sweep returned
four identical values because a quoting bug corrupted the source while the compile error
hid behind `/dev/null`. Never redirect a build to `/dev/null` inside a measurement loop.

### Phase 2 — Data layer

| # | Task | Depends |
|---|---|---|
| T08 | Drift schema | T01 |
| T09 | Trip repository | T08, T05 |

**T08** — Mirror `app/schemas/com.rippr.data.AppDatabase/2.json`: `Trip` (with
`TripState` RECORDING/PAUSED/COMPLETED), `Segment`, `TrackPoint`; FK `CASCADE`, indices on
`tripId`/`segmentId`, WAL. Starts at Dart schema version 1 with real migrations from day
one — the destructive fallback never comes back.

**T09** — Port `TripRepository`: every transition idempotent inside a transaction,
`startTrip` **adopts** an active trip rather than duplicating one, `mergeTrips`
re-parents segments and points without ever joining segments, then recomputes aggregates.

**A quiet win here:** `TripRepositoryTest`, `SchemaTest`, and `MergeTest` (666 lines) are
*instrumented* tests today, needing a device. Against Drift on the Dart VM they become
plain unit tests — faster, and runnable without an emulator booted.

### Phase 3 — Recording engine *(the risky phase)*

| # | Task | Depends |
|---|---|---|
| T10 | Location source seam | T03 |
| T11 | Recording pipeline | T09, T10 |
| T12 | Android foreground service | T11 |
| T13 | iOS background location | T11 |
| T14 | Process-death resume | T11, T12, T13 |

**T10** — A `LocationSource` interface with a `geolocator` implementation and a fake for
tests. This seam is what makes the engine testable without a device, and it is also the
escape hatch: if `geolocator` proves unreliable on a real iOS ride, swapping in
`flutter_background_geolocation` becomes one implementation rather than a rewrite.

**T11** — The heart. Unbounded `StreamController`, single async drain loop batching 25
fixes / 2 s, accumulator folded per batch, aggregates persisted per flush. Five actions:
start / pause / resume / stop / discard. Pause closes the open segment; resume opens a new
one. **Stamp `tripId`/`segmentId` at point creation** — a fix in flight during a pause must
land in the segment it actually belongs to. Stop discards a trip with zero points.

**T12** — `flutter_foreground_task` for process liveness and the persistent notification,
`foregroundServiceType="location"`, wake lock, notification actions. Configured **without**
a separate Dart isolate — the recording loop stays on the main isolate, so there is never
cross-isolate access to one SQLite file.

**T13 — where the platforms genuinely diverge.** `Info.plist` needs
`NSLocationWhenInUseUsageDescription`, `NSLocationAlwaysAndWhenInUseUsageDescription`, and
`UIBackgroundModes: [location]`, with **context-rich** strings — generic ones are the
leading cause of Guideline 5.1.1 rejection. Set `allowsBackgroundLocationUpdates = true`
and `pauseLocationUpdatesAutomatically = false`. Then **document and measure** what
actually happens when the bike stops at a light versus parks for ten minutes; the app must
resume cleanly rather than silently ending a ride.

**T14** — On launch, adopt any trip with `endedAt IS NULL` and restore the accumulator from
the persisted row, matching the Kotlin restart path. Verify by force-killing mid-ride on
both platforms.

### Phase 4 — UI

| # | Task | Ports | Depends |
|---|---|---|---|
| T15 | Shell: router, Riverpod, theme | `RipprNavHost`, `ui/theme/` | T01 |
| T16 | Record screen | `ui/record/` | T11, T15 |
| T17 | Trips list | `ui/trips/` | T09, T15 |
| T18 | Trip detail: stats + charts | `ui/detail/`, `ui/components/Stats.kt` | T04, T15 |
| T19 | Map + path rendering | `ui/components/RideMap.kt` | T02, T18 |
| T20 | Rename / delete / merge | | T17, T18 |
| T21 | Export UI | T06 | T18 |

**T15** — Functional dark + safety orange, matching the icon. The theme must set a default
content colour: in Compose, removing `Surface` once made a 64 sp speed figure render
black-on-black and **no test caught it — only a screenshot did**. Flutter's equivalent
exposure is `DefaultTextStyle`.

**T16** — Headline is **live speed plus a wall-clock elapsed ticker**, not max speed. v2.0
shipped max-speed-as-headline and it read as a frozen, broken screen on a real ride,
because on an emulator every value is zero and a number that never moves looks fine.
Keep the 72 dp glove-sized controls; confirm on Discard only.

**T19** — Per-segment polylines so pauses leave visible gaps, speed-bucketed colouring,
Douglas–Peucker decimation **render-only**, fit-to-bounds followed by a **zoom clamp**: a
50 m ride once zoomed past OSM's max tile zoom of 19 and rendered an empty grid. Set a real
user agent before any tile fetch or OSM returns 403, and cache tiles in app-private
storage. Guard the map's own bounds so it cannot overdraw adjacent controls.

### Phase 5 — Verification

| # | Task | Depends |
|---|---|---|
| T22 | Uploader + config | T09 |
| T23 | Widget tests | Phase 4 |
| T24 | Integration tests, both platforms | Phase 4 |
| T25 | Real-ride validation | T24 |
| T26 | iOS release readiness | T25 |

**T22** — `package:http` uploader with batching, retry, offline-safe backlog via the
`synced` column, carrying `trip_id`/`segment_id` in the payload. `shared_preferences` for
endpoint, `deviceId`, `mapEnabled`. Parity note: this still has **no UI**, exactly as today.

**T23 — closes v2's largest known gap.** Zero UI tests exist across six screens today;
Flutter makes widget tests cheap enough that there is no excuse to carry that debt into the
port. Cover navigation record→trips→detail→back, empty states, chart degradation below two
points, and merge enabled only at exactly two selections.

**T25** — Run the checklist in `docs/TESTING.md` on **both** platforms. Non-negotiable,
because **neither simulator can produce velocity** — `adb emu geo fix` teleports and the
iOS simulator's synthetic locations are no better, so max speed, average moving speed,
moving time, and **speed colouring on the map** are all unverifiable in CI. Also ride
**short and long**: a ~900 m fixture hid the short-ride zoom bug completely.

**T26** — Privacy nutrition labels matching actual runtime behaviour, usage strings
audited, background-location justification ready for review.

### Phase 6 — Cutover

| # | Task | Depends |
|---|---|---|
| T27 | Parity audit and handover | all |

Walk the v2.0.1 feature table row by row and demonstrate each on both platforms. **Do not
tick boxes in bulk** — a v2 task once had every criterion checked by a blanket regex
including items never actually verified. Then: port `ARCHITECTURE.md` with the decisions
that changed, carry `docs/v3/BACKLOG.md` forward, and mark the native repo archived with a
pointer to its replacement.

---

## Dependency graph

```
T00 ─► T01 ─┬─► T02 ─┬─► T04 ─► T05 ─┐
            │        └─► T06 ─┐      │
            │  T03 ──► T04    │      │
            │        └─► T10  │      │
            │                 │      │
            ├─► T08 ─► T09 ───┼──────┴─► T11 ─┬─► T12 ─┐
            │            │    │               ├─► T13 ─┼─► T14
            │            │    │               │        │
            └─► T15 ─┬───┼────┼───────────────┘        │
                     │   │    │                        │
        T02─┬─► T07  │   │    │                        │
            │        │   │    │                        │
            └────────┴───┴────┴─► T16/T17/T18 ─► T19 ─► T20/T21
                                                          │
                              T22 ──────────────────────► T23 ─► T24 ─► T25 ─► T26 ─► T27
```

Critical path: **T00 → T01 → T08 → T09 → T11 → T12/T13 → T14 → T16 → T24 → T25 → T27**.

Phase 1 is almost entirely parallelisable and carries near-zero risk — but per your v2
preference, everything runs **sequentially** so dependent architecture surfaces before it
becomes expensive to change.

---

## Key risks

| Risk | Mitigation |
|---|---|
| **Disk space blocks the toolchain** | T00 gates everything; hard exit criteria before any code |
| **iOS suspends a stationary app mid-ride** | T13 measures it explicitly; T10's seam makes swapping to `flutter_background_geolocation` cheap if free tooling loses rides |
| `geolocator` proves less reliable than FusedLocation | T25 rides both a real Android and a real iOS device before the native app is retired |
| Elevation hysteresis subtly mistranslated | T07 asserts six-decimal agreement against the Kotlin implementation |
| Two isolates racing one SQLite file | Avoided by design — foreground service provides liveness only, recording stays on the main isolate |
| Decimation leaking into storage or export | Render-only, and T06's ported tests assert exact point counts |
| Simulators hide velocity-dependent bugs | Stated up front in T25; **a green suite proves nothing about speed** |
| Silent parity loss | T27 audits the feature table row by row, demonstrated not asserted |

---

## Verification

```bash
flutter analyze && flutter test                      # pure logic, data layer, widgets
flutter test integration_test -d <android-emulator>
flutter test integration_test -d <ios-simulator>
flutter build apk --debug && flutter build ios --debug --no-codesign
```

Plus the **cross-language parity harness** (T07): identical fixtures through Kotlin and
Dart, agreement asserted to six decimals — the port's strongest single guarantee, and the
reason Phase 1 comes first.

**Definition of done:** every row of the v2.0.1 feature table demonstrated on a real
Android phone *and* a real iPhone, the `docs/TESTING.md` checklist passed on both, and no
capability lost.

---

## Open question, deferred deliberately

The native app's known **elevation drift** (~30 m per ten stationary minutes against
synthetic noise) ports along with the algorithm — faithfully, bug included. That is correct
for a parity port: fixing it during translation would make any differential test failure
ambiguous. It stays in the v3 backlog, where it already says *do not tune this blind*.