Mobile Offline Sync

Make the local store the source of truth the UI reads and writes, and treat the network as eventual replication. The hard part is never the happy path - it is reconciling divergent edits made while offline. The costly failure is an ad-hoc "retry the request later" queue that double-applies mutations, resurrects deleted rows, and silently destroys one user's edits with another's.

Operating procedure

Step 1: Gather inputs

Collect per feature before designing:

1. The entities that must work offline, and for each: single-owner or multi-writer? Whole-object edits or field-level edits?
2. The maximum realistic offline window (a field-service app may need 7-30 days; a consumer app usually hours). This sets tombstone retention.
3. The local store (Room, SwiftData, SQLite, Realm) and whether the server API can accept client-generated UUIDs and return per-record versions.
4. Which operations are strong-consistency (payments, inventory decrements, seat booking) - these get disabled offline, not synced.
5. Expected data volume per user, which decides pull batch sizes.

Label unknowns as guesses and validate them against the server team before building.

Step 2: Make the local store the UI's truth