Offline‑first design

The pattern

An offline‑first app treats the network as an enhancement, not a requirement. Every user action succeeds immediately against a local store. A background sync engine reconciles changes with the server when connectivity returns, using CRDTs or last‑writer‑wins merging.

Local store

SQLite via better‑sqlite3 or the native VFS layer. Keep a monotonically increasing sequence number per row. Every mutation increments the sequence and marks the row dirty. The sync engine walks dirty rows oldest‑first, pushing them to the server.

Sync engine

A dedicated thread or Web Worker polls the server with exponential backoff (1s → 30s cap). On success it pulls remote changes since the last known server sequence, merges them into the local store, and clears dirty flags. Conflicts resolve with a simple timestamp comparison — the most recent write wins.

Graceful degradation

Every network call is wrapped in a 5‑second timeout. On failure the UI shows a subtle amber dot — never a modal. Queued mutations stay in the dirty table. When the dot turns green, the user knows sync completed. No data is ever lost.

Checklist

• ▸Local SQLite store with sequence column
• ▸Dirty‑row tracking for pending mutations
• ▸Background sync with exponential backoff
• ▸Last‑writer‑wins conflict resolution
• ▸Connectivity indicator — amber dot, never a modal
• ▸5‑second network timeout on every call