Offline Sync skill for Claude Code

Offline-first is done right when the UI reads only from the local database, every user write commits locally together with an outbox entry in one transaction, the sync worker replays the outbox idempotently and pulls deltas by server cursor, conflicts are resolved by an explicit rule per entity, and no write is ever dropped silently.

Decide the level of offline support

Level	Behavior	Cost
0. Online-only with cache	Show last-fetched data read-only; block writes offline	Low — HTTP cache or query cache persistence
1. Offline reads	Local DB mirrors server data; writes need network	Medium
2. Offline writes, rare conflicts	Outbox + LWW per record; user-owned data	Medium-high
3. Collaborative offline edits	Field merges, operations, or CRDTs; conflict UI	High

Pick the lowest level that meets the product need, per entity. A notes app needs level 2–3 for notes and level 1 for the template catalog.

Workflow

- [ ] 1. Classify entities: offline level, ownership, conflict likelihood
- [ ] 2. Choose local storage (and whether a sync engine replaces custom sync)
- [ ] 3. Schema: client IDs, server version, tombstones, local sync status
- [ ] 4. Write path: local write + outbox in one transaction
- [ ] 5. Push: ordered, batched, idempotent, retry with backoff, poison handling
- [ ] 6. Pull: cursor-based deltas including deletes, applied transactionally
- [ ] 7. Conflict rule per entity + optimistic UI states
- [ ] 8. Triggers, auth expiry, logout wipe, migrations
- [ ] 9. Chaos tests: airplane mode, kill mid-sync, two devices, clock skew

Local storage choice

Platform	Default	Alternatives
iOS native	SwiftData (iOS 17+) or GRDB (SQLite, precise control)	Core Data
Android native	Room (SQLite) with Flow queries	SQLDelight
React Native / Expo	expo-sqlite or op-sqlite; WatermelonDB for large reactive datasets	MMKV for small key-value only
Flutter	Drift (SQLite, reactive streams)	sqflite
Want sync handled for you	PowerSync, ElectricSQL, Couchbase Lite, Firestore offline persistence	Evaluate vendor lock-in and conflict model

MongoDB Realm / Atlas Device Sync reached end of life in 2025; plan migrations off it. Key-value stores (AsyncStorage, UserDefaults, SharedPreferences) are not databases: no queries, no transactions — do not build sync on them.

Schema

CREATE TABLE tasks (
  id            TEXT PRIMARY KEY,          -- client-generated UUIDv7/ULID: works offline, sortable
  title         TEXT NOT NULL,
  done          INTEGER NOT NULL DEFAULT 0,
  updated_at    TEXT,                       -- server timestamp, informational
  version       INTEGER,                    -- server-assigned, increments per change; NULL = never synced
  deleted       INTEGER NOT NULL DEFAULT 0, -- tombstone; hard-delete only after server confirms
  sync_status   TEXT NOT NULL DEFAULT 'synced'  -- synced | pending | failed
);

CREATE TABLE outbox (
  seq             INTEGER PRIMARY KEY AUTOINCREMENT,
  entity          TEXT NOT NULL,
  entity_id       TEXT NOT NULL,
  op              TEXT NOT NULL,            -- create | update | delete | domain op e.g. 'complete'
  payload         TEXT NOT NULL,            -- JSON: changed fields only + base_version
  idempotency_key TEXT NOT NULL UNIQUE,
  attempts        INTEGER NOT NULL DEFAULT 0,
  last_error      TEXT,
  created_at      TEXT NOT NULL
);

CREATE TABLE sync_state (scope TEXT PRIMARY KEY, cursor TEXT);

Write path

await db.transaction(async (tx) => {
  await tx.run("UPDATE tasks SET done = 1, sync_status = 'pending' WHERE id = ?", [id]);
  await tx.run(
    "INSERT INTO outbox (entity, entity_id, op, payload, idempotency_key, created_at) VALUES (?,?,?,?,?,?)",
    ["task", id, "update", JSON.stringify({ done: true, base_version: task.version }), uuidv7(), nowIso()],
  );
});
syncScheduler.kick();   // best effort; the outbox survives app death

• Local write and outbox insert must be one transaction, or a crash between them loses or orphans the change.
• Send changed fields plus base_version (the version the edit was based on), not the whole record — this enables field-level merges and conflict detection.
• The UI observes the local DB reactively and shows pending state (subtle icon); it never waits on the network.

Push

1. Read outbox in seq order, batch (e.g. 50 ops), send with each op’s idempotency key.
2. Server applies each op idempotently (stores processed keys for at least the max offline window), validates, increments version, returns the canonical record or a conflict.
3. On success: delete the outbox rows and write the canonical record locally with sync_status = 'synced' — unless newer local ops for that entity are still queued.
4. Transient failures (network, 5xx, 429): stop the batch, retry with exponential backoff plus jitter (e.g. 1 s, 2 s, 4 s … cap 5 min), preserving order.
5. Permanent rejection (400 validation, 403): mark the entity failed, keep the op with last_error, surface it to the user (“Couldn’t save — tap to review”). Never drop it silently, and do not let it block unrelated entities forever (move it to a dead-letter state).

Ordering: keep ops for the same entity in order. Coalescing multiple updates to one entity into one op is fine; reordering a delete before a create is not.

Pull

GET /sync/changes?since=opaque-cursor-123&limit=500
→ { "changes": [ { "entity": "task", "id": "...", "version": 18, "deleted": false, "data": {...} } ],
    "next_cursor": "opaque-cursor-456", "has_more": true }

• The cursor comes from the server (sequence number, LSN, or change-log ID) — never the device clock, which is wrong on many devices.
• Deletes arrive as tombstones; a server that only returns live rows cannot propagate deletions.
• Apply each page in one local transaction and save next_cursor in the same transaction.
• If a pulled record has pending local ops, do not blindly overwrite it: apply the conflict rule (below) or rebase the pending ops on the new server version.
• Provide a full resync path (cursor reset) for corrupted state or when the server says the cursor is too old (e.g. HTTP 410).
• Order: push first, then pull, so the pull reflects your own writes.

Conflict resolution

Entity type	Rule
User-owned, single editor (settings, drafts)	Server-versioned last-writer-wins on the record
Shared records, different fields edited	Field-level merge: apply fields whose server value still equals the base
Counters, inventory, balances	Send operations (increment by 2), never absolute values; server validates
Collaborative text or lists	CRDT (Yjs, Automerge) or server-side operational transform
High-stakes data (orders, payments)	Server authoritative; client ops are requests that can be rejected
Conflicts users must decide	Keep both versions and show a resolution UI

LWW must compare server versions or server receive order, not device timestamps. For detailed algorithms, merge examples, and server-side conflict detection, read references/conflict-resolution.md when an entity needs anything beyond record-level LWW.

Sync triggers

• App launch and foreground; after each local write (debounced 1–2 s); connectivity regained (NWPathMonitor on iOS, ConnectivityManager.NetworkCallback on Android, NetInfo in RN, connectivity_plus in Flutter).
• Background: Android WorkManager with a NetworkType.CONNECTED constraint (unique work, KEEP policy); iOS BGAppRefreshTask/BGProcessingTask — opportunistic, not guaranteed; silent push as a hint (see mobile-push-notifications).
• Connectivity APIs report a network path, not that your API is reachable. Always handle request failure even when “online”.
• Run one sync at a time (a mutex or single worker); overlapping syncs duplicate pushes.

Auth, security, lifecycle

• Expired tokens while offline: queue stays intact; refresh on reconnect; if refresh fails, require sign-in but keep the outbox for the same user.
• Logout: confirm with the user if the outbox has unsynced changes, then wipe the local DB (or use one DB file per user). Never show user A’s data to user B.
• Encrypt sensitive local data (SQLCipher, iOS Data Protection classes, Android encrypted storage for keys).
• Local schema migrations must preserve the outbox. Version outbox payloads so a new app version can still send ops queued by the old one.

Verification

1. Airplane mode: create, edit, delete; kill the app; relaunch offline — all changes visible and pending. Go online — outbox drains, server matches.
2. Throttle to a lossy network (Network Link Conditioner on iOS, emulator network settings on Android); toggle connectivity mid-sync. No duplicates on the server (check idempotency keys) and no lost edits.
3. Two devices edit the same record offline, then sync: the result follows the documented rule for that entity.
4. Set the device clock a day off: sync still converges.
5. Force a permanent server rejection: the item shows a failed state with a recovery action, and other entities keep syncing.
6. Delete on device A, sync, then sync device B: the record disappears on B.