Offline-First Apps: Local Storage, Sync and Conflict Resolution

An offline-first app treats the device's local database as the primary source the UI reads and writes, and synchronises with the server in the background whenever a connection is available. Users can keep working on a plane, in a basement or on a flaky network, and their changes are never lost. The design centres on four pieces: a local store, an outbox of pending changes, incremental sync from the server, and a rule for resolving conflicts.

Architecture

Writing locally: the outbox

1. A user action writes to the local database immediately, so the UI updates instantly, and appends a mutation to an outbox in the same local transaction.
2. Each mutation has a client-generated unique ID (an idempotency key) and, for new records, a client-generated record ID such as a UUID, so the record can be referenced before the server knows about it.
3. The sync engine sends outbox entries in order when online, retrying with backoff. The server deduplicates by mutation ID, so retries after a lost response are safe.
4. Once acknowledged, the entry is removed. If the server rejects it (validation, permissions), the app must show the user and roll back or fix the local change.

Reading changes: delta sync

• The server keeps a monotonically increasing change sequence (or per-table updated-at versions) and exposes "give me changes since cursor X".
• The client stores the last cursor it applied and pulls only newer changes, in pages. A fresh install does an initial full sync, which may need to be limited to recent or relevant data.
• Deletes must be represented as tombstones in the change feed, otherwise clients never learn that a record disappeared.
• Push notifications or a real-time channel can tell the client to pull sooner, but the pull protocol stays the source of truth. See push notifications.

Conflict resolution

Two devices edit the same record while one is offline. When both sync, which wins?

Some operations can't be offline-first: paying, booking the last seat, or anything with a global invariant. Queue them as requests with a clear "pending" state, and confirm with the server before showing success.

Practical concerns

• Background sync: platforms limit background work to save battery; sync opportunistically when the app is opened, on connectivity changes, and through OS background tasks.
• Schema migrations for the local database must run safely on old app versions' data, and the sync protocol must tolerate clients on old versions. See mobile release engineering.
• Storage limits and eviction: decide what to keep locally and how to page in older data.
• Security: encrypt sensitive local data and wipe it on sign-out.
• UX: show sync status, pending changes and conflicts clearly, so users trust the app.