Offline-first architecture
Offline-First Mobile Architecture
Offline-first is a product consistency decision, not a cache toggle.
Short answer
What matters most
Offline-first mobile architecture makes durable local data the immediate source of truth and synchronizes it with the server under explicit consistency rules. The design must distinguish cached reads from pending user writes, assign stable identifiers, make writes idempotent and expose synchronization state to the UI. Conflict policy depends on the domain: last-write-wins may suit preferences, while collaborative edits or financial actions require stronger rules. Background execution should improve freshness but cannot be the only path to correctness. A robust design survives retries, duplicate delivery, clock drift, schema migration and app termination. The user should know when data is saved locally, pending remotely or blocked by a conflict.
Choose the source of truth
If screens read from both network responses and a database, state can diverge. Prefer one observable local model and let synchronization update it.
- Durable local entities
- Pending mutation metadata
- Server version or revision
- Last successful synchronization
- Conflict and failure state
- Migration version
Design writes as a state machine
A write moves from local intent to queued, sending, acknowledged or failed. Retrying must not duplicate the action, and permanent failure needs a visible recovery path.
Separate safe automatic retries from actions that require the user to decide again.
Test the ugly timeline
Test app termination during a write, an old device reconnecting, token expiry, reordered responses and schema changes while the queue is nonempty.
These timelines reveal whether offline-first is real or only a successful-demo path.
