Lesson 7 of 11 ·12 min read

1. Why this is the hard part

On the web you may assume the network exists; when it doesn't, the page fails and the user retries. An app cannot do that. It is expected to open instantly in a tunnel, show everything the user cares about, and never lose what they typed. The moment you honour that expectation, the app becomes a distributed system: a database on the phone and a database behind your API, disconnected most of the time, that must eventually agree.

Everything in this lesson is downstream of that sentence. The good news: the complexity comes in well-understood tiers, and most apps only need the cheap ones.

2. The ladder of offline support

Offline support is not one feature. It is a ladder, and each rung costs roughly ten times the one below it. The most important design decision is picking a rung deliberately instead of drifting up the ladder by accident.

3. The architecture: single source of truth

From rung 2 upward, the pattern that keeps everything sane is:

        WRONG (fetch-and-render)               RIGHT (single source of truth)

   UI <--- render ---- network response      UI <-- reactive query -- local DB
   |                                                                     ^
   +-- spinner while fetching,               network sync layer ---------+
       blank when offline                    (background: pull deltas,
                                              push outbox)

The payoff: the app behaves identically online and offline (same code path, same screens), just with fresher or staler data. Loading spinners mostly disappear; "offline mode" stops being a mode. Every serious on-device store is built around this reactive-query pattern: Room (Android), Core Data / SwiftData (iOS), WatermelonDB (React Native), Drift (Flutter); nearly all of them SQLite underneath.

4. Offline writes: the outbox pattern

Writes made offline go into a local outbox: a table of pending operations.

-- the outbox, conceptually
id (uuid)  | op      | payload                        | created_at | attempts
a1b2...    | create  | {"list":"wk32","text":"..."}   | 10:41      | 0
c3d4...    | rename  | {"item":"789","text":"..."}    | 10:44      | 0

1. Optimistic UI: the local write happens immediately and the UI updates from the local DB: the user sees their change now, not after upload.
2. A background drainer sends queued operations, in order, when connectivity returns.
3. Idempotency keys: each operation carries its client-generated UUID; the server treats a repeated key as "already done, return the previous result." This solves the classic failure: the network dies after the server processed the request but before the response arrived. Without the key, the retry creates a duplicate.
4. Retries with exponential backoff, preserving per-item order; an operation that keeps failing for a non-network reason (validation, permissions) must surface to the user, not retry forever.

5. Conflicts, and how real apps mostly dodge them

A conflict: you edited a note offline; the same note changed server-side meanwhile (another device, another user). The textbook resolution strategies, in ascending order of effort:

The practical wisdom, though, is that well-designed apps avoid most conflicts structurally instead of resolving them heroically:

• Ownership: data owned by one user, edited from one device at a time, rarely conflicts. Most personal apps are here by default.
• Append-only shapes: log entries, messages, orders, events cannot conflict: two devices appending produces two entries, both valid. Modelling edits as appended events ("renamed X at 10:41") rather than mutated records makes sync dramatically easier.
• Narrow writes: "update this one field" conflicts far less often than "replace this whole record."

Design the data model first; reach for resolution machinery only where genuinely concurrent editing survives the redesign.

6. What sync demands from your API

A "sync-ready API" is a specific, learnable shape with five features:

1. A delta endpoint: GET /items?since=<cursor> returning only what changed plus a new cursor, instead of the full collection every time. (A cursor issued by the server beats a client-supplied timestamp: clocks skew, and a server cursor can encode ordering exactly.)
2. Tombstones: deletions must appear in the delta as explicit markers ("deleted": true). A row that simply vanishes from responses can never be noticed by a client that already holds it. This is the classic sync bug: ghosts that live forever on the phone.
3. Idempotency keys accepted on all writes (§4).
4. Versioned writes with 409 + current server state on staleness (§5).
5. Batch endpoints: draining a 50-item outbox should not be 50 round-trips on hotel WiFi; accept an array, return per-item results.

GET /planner/items?since=cursor_8fk2
→ {
    "changes": [
      { "id": "123", "text": "Send curl tool to PyCoder's", "version": 7 },
      { "id": "98",  "deleted": true }              ← the tombstone
    ],
    "next_cursor": "cursor_9am1"
  }

7. Buy vs build

8. Common gotchas

9. Applying it: the planner app

For a personal planner client (from Building Your First App), the right answer is deliberately low on the ladder:

• Rung 2 is the target. Cache the planner blob locally, render instantly on open, refresh in the background, pull-to-refresh for manual sync. This is most of the felt benefit for a screen's worth of code.
• Writes: either require connectivity to edit (honest and simple), or keep a one-slot outbox for the single "update the blob" operation with an idempotency key.
• Conflicts: one user, mostly one device at a time: structurally dodged. If the phone and the desktop planner ever race, versioned writes on the blob (reject-and-refresh on 409) is one afternoon of work.

Reviewed 4 August 2026.