Building Resilient Offline-First Mobile Architectures

A mobile app should never present an empty spinner when internet connectivity drops. For utility and productivity tools like PlanEatRepeat, offline capability is not a fallback—it is the baseline contract.

In this technical breakdown, we look at how to structure local persistence, optimistic updates, and conflict resolution across iOS and Android.

1. Single Source of Truth (SSOT) via Local Database

A common anti-pattern in mobile development is treating the network API as the primary source of truth and local storage as an optional cache. In an offline-first architecture, the flow is reversed:

1. User Action: The UI modifies local state immediately (optimistic UI).
2. Local Persistence: Changes are committed to the local database (SwiftData / SQLite on iOS, Room on Android).
3. Reactive UI Update: The UI observes the local database query and updates instantaneously.
4. Outbox Synchronization: An asynchronous background sync engine attempts to push changes to the remote API.

[User Action] ──> [Local Database (SSOT)] ──> [Reactive UI Observation]
                         │
                         └──> [Sync Engine / Outbox Queue] ──> [Cloud Backend]

2. Handling Merge Conflicts with Vector Clocks & LWW

When multiple devices modify shared data—such as two family members editing a grocery list simultaneously—conflicts inevitably occur. We implement a hybrid strategy:

• Field-level Last-Write-Wins (LWW): Timestamps are recorded per attribute rather than per entity record, avoiding unnecessary overwrites of unrelated changes.
• Append-Only Event Logs: Complex actions (like item reordering or quantity increments) are modeled as discrete events rather than raw database row replacements.

3. Background Sync & OS Lifecycle Constraints

Both iOS (BGAppRefreshTask) and Android (WorkManager) impose strict execution windows and battery conservation rules. By queuing compact differential payloads into an indexed outbox table, synchronization completes in sub-second background bursts when network conditions stabilize.