samplez/rippr-src/docs/ARCHITECTURE.md

Architecture

The decisions that shaped Rippr, and — more usefully — why. Several exist because something specific went wrong; those are marked.

---

The recording pipeline

onLocationResult (main looper)
   │  stamp tripId + segmentId, sanitize speed, reject bad-accuracy fixes
   ▼
Channel(UNLIMITED) ──► single writer coroutine (Dispatchers.IO)
                          │  batches of 25, flushed every ~2s, under writeMutex
                          ├─► insertPoints()
                          └─► Accumulator.fold() → updateAggregates() on the Trip row

Why an unbounded Channel

The location callback must never block. Writing to SQLite from inside onLocationResult would couple GPS delivery to disk latency, and a slow flash write would drop fixes. The channel decouples them: the callback's trySend never suspends, and back pressure stalls the writer, not the sensor.

Do not replace this with a direct write. It is the single most load-bearing decision in the recording path.

Why points are stamped at creation

Each TrackPoint carries its tripId and segmentId from the moment it is built in the callback, not looked up at write time.

This makes pausing safe: a fix already queued when the rider pauses lands in the segment it was actually recorded during, whatever order the writes happen in.

Correction worth remembering. The v2 plan originally claimed that closing a segment before draining the channel would misfile points. That was wrong — stamping at creation already prevents it. Draining before closing is still done, but as robustness (not leaving points unwritten while a ride idles), not correctness. If anyone ever refactors stamping into a write-time lookup, this guarantee disappears.

Why batched writes

A 2 Hz stream would otherwise mean two transactions per second for hours. Batching to 25 points or 2 seconds — whichever comes first — cuts that to one write per two seconds.

Why WAL journal mode

A ride is unrecoverable if writes are lost to a crash, but fsync on every insert at 2 Hz burns battery. WAL with NORMAL sync survives app crashes; only an OS-level crash can lose the last few points. That is the accepted trade.

Why the wake lock

A foreground service alone does not guarantee CPU time with the screen off on all OEMs. A PARTIAL_WAKE_LOCK keeps the writer coroutine running. It is released on pause — a lunch stop has no business holding the CPU awake — and re-acquired on resume.

---

Data model

Trip 1───* Segment 1───* TrackPoint

Trip(id, startedAt, endedAt?, name?, state,
     distanceM, movingMillis, maxSpeedKmh, elevationGainM, pointCount)
Segment(id, tripId, startedAt, endedAt?)
TrackPoint(id, tripId, segmentId, timestamp, lat, lon, speedKmh, altitudeM,
           accuracyM, bearingDeg, synced)

Why Segment exists

Three of the four things v1 lacked — reset, pause, and trips — were the same missing concept. Segments are what make pause correct: they represent a pause-free stretch of recording, so every consumer naturally leaves a gap where the rider stopped.

They propagate into three places, and all three would be wrong without them:

• Distance accumulates only within a segment
• Map polylines are drawn one per segment, never joined
• GPX emits one <trkseg> per segment, which is exactly how GPX represents a gap

Why both endedAt and state

endedAt == null distinguishes active from finished, but cannot distinguish RECORDING from PAUSED. The service needs that difference to decide what to do when the OS restarts it mid-ride.

Why aggregates are denormalised onto Trip

minSdk 26 means SQLite 3.18, which has no window functions — no LAG, no OVER. There is simply no SQL expression for "distance from the previous point". So consecutive-point maths happens in Kotlin, in the writer loop that already touches every point, and the result is persisted on the Trip row.

This also keeps the trips list fast: it reads only Trip rows, never the point table, so it stays responsive with hundreds of rides.

Ordering is by (segmentId, id), never timestamp

timestamp comes from Location.time, which is GPS-derived and can jump. The autoincrement id is genuinely monotonic in write order.

Migrations are mandatory

fallbackToDestructiveMigration() was used during v2 development, when the only data was throwaway test rides, and removed in T18. Any schema change from here must ship a Migration against app/schemas/com.rippr.data.AppDatabase/2.json. Reinstating the fallback would silently delete every stored ride on the next version bump.

---

State ownership

Recording state is derived from the database, never held in memory.

v1 kept an in-memory flag. It lied after process death: START_STICKY restarts the service with a null intent, and the flag came back false while a ride was genuinely underway. This was verified fixed by force-stopping the app mid-ride — the button correctly still read STOP.

TripRepository owns every transition, each in a withTransaction, and each is idempotent:

Transition	Behaviour on an unexpected state
startTrip	Adopts an already-active trip rather than creating a second
pauseTrip	No-op if already paused
resumeTrip	No-op if already recording — never opens a duplicate segment
completeTrip / discardTrip	No-op with no active trip

Idempotency is not defensive padding: the OS can restart the service at any moment, and these are the states it can restart into.

Ephemeral state is separate and deliberate

Two objects hold genuinely transient state that should be lost on restart: UploadStatus (last upload error) and LiveTelemetry (current speed, published from the GPS callback at sensor rate so the speedo does not wait on the 2-second flush).

---

Statistics

Computed twice, deliberately, by the same code:

• Live, folded per batch into Accumulator, so the screen shows moving numbers
• Authoritatively, via RideStatistics.compute() over stored points when a trip completes, overwriting the live estimate

A mid-ride process kill loses the in-memory accumulator, so the live figure can drift. Recomputing at completion with the same functions keeps the two consistent by construction rather than by discipline.

The cross-batch anchor

Accumulator keeps the last point of the previous batch. Without it, distance restarts at every flush boundary and under-reports by roughly one hop per batch — a few percent, invisible until compared against an odometer. A unit test asserts that chunked folding equals single-batch folding.

Elevation gain needs two mechanisms

This is the subtlest maths in the codebase, and it was measured, not assumed.

A naive "sum every delta above a 3 m threshold" reported 1498 m of climbing over a parked bike with ±8 m altitude noise, because noise crosses any small threshold constantly.

The shipped version combines:

1. A 15-sample moving average, cutting noise by roughly √window
2. Reversal hysteresis — a climb banks only once altitude turns back down past the threshold from its peak

That brings the same fixture to ~30 m. Smoothing then clipped real terrain (a 100 m climb measured 93 m, since a moving average lags by half a window), so finish() reconciles the final run against the last raw reading.

~30 m of drift per ten stationary minutes remains. The regression test guards against returning to 1498 m; it is not a claim of accuracy.

Other definitions worth knowing

• Average speed is distance ÷ moving time, not the mean of speed samples. The mean over-weights time spent stopped.
• Sample gaps are capped at 10 s. Without it, a two-minute tunnel counts as two minutes of moving time at the last known speed.
• The speed histogram is weighted by time, not sample count.
• Division guards everywhere — a NaN reaching Compose renders as the literal text "NaN".

---

UI

MainActivity (74 lines) owns only runtime permissions and the battery-optimisation prompt. Everything else is ui/{theme,components,record,trips,detail} with one ViewModel per screen behind a single factory. No DI framework — three screens do not earn Hilt.

Two hard-won UI lessons

Surface is load-bearing, not decoration. Moving the UI out of the old Surface wrapper made LocalContentColor default to black, rendering the 64sp speed figure invisible against the near-black ground. Text with an explicit colour still showed, so the screen looked merely odd rather than broken. RipprTheme now wraps content in a Surface. No test would have caught this — only looking at a screenshot did.

Show current speed, not max. The first real ride reported the screen as frozen. A max figure only moves when you beat it, so riding steadily leaves it motionless. The headline is now current speed, with max demoted to the stats card, and a wall-clock elapsed timer ticks every second independent of any database write.

Control layout

State	Primary	Secondary
Idle	START RECORDING	—
Recording	PAUSE	STOP
Paused	RESUME	STOP · DISCARD

Discard appears only while paused. A destructive control next to Pause during a live ride invites a gloved mis-tap at speed. Buttons are 72dp/56dp because they get pressed with gloves on.

---

Map

osmdroid, chosen over MapLibre and Google Maps because it needs no API key, no billing account, and no GCP project, and it caches tiles for offline use — which matters on mountain rides.

Three things that will break it if disturbed:

1. The user agent must be set before any MapView is constructed. osmdroid's default is rejected by OSM's tile servers with a 403, and the failure presents as an empty map rather than an error. Set in RipprApp.onCreate.
2. onDetach() is not optional. Without it, tile handles and the downloader thread outlive the composable and the leak compounds. The MapView is hoisted into a remember so the lifecycle observer can reach the same instance the AndroidView shows — an earlier version observed the lifecycle and did nothing, because it could not see the view.
3. Zoom must be clamped. zoomToBoundingBox ignores maxZoomLevel. A 50 m ride zooms past OSM Mapnik's maximum published zoom of 19, where no tile exists, and the map renders as an empty grid. This shipped in v2.0 and was found on the first real ride.

Rendering uses bucketed polylines — runs of similar speed drawn as separate monochrome lines, overlapping by one point — rather than osmdroid's per-vertex PolyChromaticPaintList, which is fiddly and gains little at real viewing zoom.

Decimation is render-only. Geo.simplify is applied when building overlays and nowhere else. Storage and export always use raw points; the export tests assert exact counts specifically to catch a leak.

---

Export

Pure string generation with no Android dependency, so the format logic is unit-tested on the JVM.

• GPX 1.1, one <trkseg> per segment, speed in <extensions> in m/s per the spec
• GeoJSON, coordinates [lon, lat, ele] — longitude first, the opposite of GPX and the classic silent error; a test asserts it explicitly
• Timestamps inside files are UTC; filenames use local time, because a human reads the filename and a machine reads the contents
• Names are XML- and JSON-escaped — a ride called Sam & Dave's <ride> would otherwise produce a malformed file, and the failure is invisible until an import rejects it

Delivery is via FileProvider and the share sheet. A raw file:// URI throws FileUriExposedException on Android 7+, and the receiving app needs FLAG_GRANT_READ_URI_PERMISSION or it reports a SecurityException that looks like a bug in that app.

---

Upload

TelemetryUploader is deliberately subordinate to recording: every failure is swallowed and retried, and nothing in it can stop the location pipeline. Points carry synced = 0 until the server acknowledges them, so a dead endpoint costs only a growing backlog.

trip_id and segment_id are stamped per point, not per batch, because getUnsyncedPoints() draws by id and a batch can straddle a segment or — after a discard-and-restart — a trip boundary.