Skip to Content
Front pageLabsLabs, projects & CCNA notes

Architecture

The MileWage server, web app and Android app, the engine they share, and how a shift moves between them.


The server is the single source of truth. The phone is a recorder that can work offline and send later.

Components

ComponentLocationStackRole
Serverapps/serverFastify, SQLite (better-sqlite3), Docker, CaddyStores the data, recomputes every shift, makes the backups.
Web appapps/webReact, restyled to Material Design 3Dashboard, shifts, expenses, tax, exports, backups, devices, settings.
Android appapps/androidKotlin, Jetpack Compose, Material 3Records GPS during a shift and sends it when the server is reachable.
Track enginepackages/track-engineTypeScript, no dependencies, no I/OTurns GPS fixes into distances, trips and stops.
Shared contractpackages/sharedOpenAPIThe API contract and the types generated from it.

The container limits are 192 MB for the API and 64 MB for Caddy.

Android modules

The Android app has five Gradle modules.

ModulePlatform importsContents
:engineNoneKotlin port of packages/track-engine
:coreNoneModels, formats, pairing, sending and tracking decisions
:dataAndroidRoom, OkHttp, Keystore, WorkManager
:trackingAndroidLocation service, receivers, notifications
:appAndroidCompose screens

:engine and :core contain no android.*, androidx.*, java.* or javax.* imports. A ModuleRulesTest in each module fails the build otherwise. The restriction keeps both modules portable to Kotlin Multiplatform for a later iPhone app.

Life of a shift

  1. The driver starts a shift in the Android app. A foreground service requests a GNSS fix every 5 seconds.
  2. The app stores every fix in a local database. No network connection is required.
  3. When the shift ends, the Kotlin engine computes the total and the app shows it.
  4. The app sends the raw fixes when the server is reachable.
  5. The server runs the TypeScript engine on the fixes it received.
  6. Matching totals mark the shift as matching. Different totals flag the shift and show the difference. Neither value is overwritten.
  7. The server writes an encrypted backup after the shift ends.

Constraints

  • One driver per server. There are no multi-tenant accounts.
  • No inbound ports. The phone reaches the server through tailscale serve, or through plain HTTP on private addresses only.
  • No Google Play Services. The build task check<Variant>Policy fails if a com.google.android.gms, com.google.firebase, com.google.mlkit or com.google.android.play artifact reaches the runtime classpath.
  • No silent recalculation. A finalized shift is never recomputed. After an engine upgrade, milewage-cli recalc --dry-run lists the shifts whose totals would change.
  • Hand-written request models. ContractDriftTest in :core checks the Kotlin models field by field against openapi.yaml.

Backups

The server makes a backup at 03:30 local time, after each shift, before a migration and before a restore. Each backup is verified after it is written, and a backup that fails verification is discarded.

Retention keeps the newest backup of the last 7 days, 4 Sundays and 12 first days of the month. A backup is skipped when free disk space is below twice the database size.

Verification status

Tests run on a computer only: unit tests, Robolectric screen renders and the engine cross-check against Node on x86-64. The following items are unverified:

  • The Android app on a physical phone.
  • The engine's arithmetic on arm64, on both a phone and a Raspberry Pi.
  • A shift recorded over a real Tailscale network.
Back to top