Skip to Content
Front pageLabsLabs, projects & CCNA notes

Architecture

Comma's two applications, the data model they share, and the registry pattern for countries and platforms.


Comma is a local-first monorepo. The database on each device is the source of truth for that device. Comma runs no servers and has no user accounts.

Design principles

  1. Local-first. No core feature requires a network.
  2. No backend, no account. The only external service is the driver's own Google Drive, and only on opt-in.
  3. Two apps, one model. Both apps implement the same concepts: shifts, expenses, vehicles and tax.
  4. Pluggable registries. Countries and platforms are data. Adding one is a registry file per app, registered in one place.
  5. Native where required. Background GPS on Android needs a foreground service, so tracking is a Kotlin module.

The two applications

Phone appWeb app
LocationRepository root, modules/comma-tracker/web/
FrameworkExpo and React Native, TypeScriptVanilla JavaScript, no framework
UIReact Native, NativeWindHand-written HTML and CSS modules
RoutingExpo Router (file-based)Hash router
StorageSQLite through Drizzle ORMIndexedDB through Dexie
StateZustand and TanStack React QueryModule singletons
GPSNative foreground servicenavigator.geolocation.watchPosition, tab-open only
Offline shellNative appService worker

Data split

Synced data is divided into three buckets.

BucketSyncedExamples
Device-localNoRaw location points, temporary native points
Synced recordsYesShifts, expenses, vehicles, goals, merchants
ProfileYesCountry, platforms, preferences

The bulky location tables are excluded from sync. Only the simplified route is stored with a shift.

Encryption

PropertyValue
CipherAES-256-GCM
Key derivationPBKDF2, 210,000 iterations
Salt and IVRandom, per file
Key storageThe key is never written or uploaded

Release 1.4.2 removed the unencrypted sync mode. Connecting Google Drive requires a backup password before any file is uploaded.

Known structural costs

  • The two apps use different storage engines and grew different column names and value types.
  • The sync protocol is implemented twice, in TypeScript and in JavaScript, and both must stay wire-compatible.
  • The web app cannot record GPS in the background.

The effects are described in Sync engine and GPS tracking.

Back to top