Offline-first is a consistency model
Offline-first does not mean that every feature works forever without the network. It means the product explicitly decides which actions may continue locally, how those actions are persisted, when they synchronize and how conflicts are resolved.
Start with action classes
Classify actions into three groups: local-safe, queueable and online-required. Reading a cached job list may be local-safe. Completing an inspection may be queueable. Capturing a payment authorization or checking a rapidly changing inventory may require a current server response.
The local operation queue
User action
↓
Validate locally
↓
Persist operation + clientOperationId
↓
Optimistic/local state
↓
Network available?
├─ no → retain queued
└─ yes → submit
↓
server result
↓
reconcile local statePersist the operation before claiming success to the user. Give every mutation a stable client operation ID so that retrying after a timeout cannot create a duplicate order, task or upload.
Server-authoritative does not mean poor UX
The server can remain the source of truth while the client shows immediate local progress. The distinction is whether the UI communicates pending/synchronized/failed state accurately. A field technician can continue working while synchronization happens later, without pretending the backend already accepted every action.
Conflict policy must be domain-specific
“Last write wins” is not a universal solution. A note can often merge or overwrite safely. An inventory allocation, rental booking or compliance measurement may require stricter rules. Define conflict policy per entity and operation.
Attachments need their own state machine
Photos, videos, signatures and documents are often the heaviest offline objects. Separate metadata creation from binary upload and track upload state independently so a failed photo transfer does not invalidate the entire business record.
Background synchronization is opportunistic
Mobile operating systems constrain background execution. Build sync so it can resume when the application becomes active, when connectivity returns or when the platform grants background time. Do not rely on an infinite background worker.
What support needs to see
Expose operation ID, device/app version, local timestamp, synchronization attempts and server result. Otherwise support receives “the app says it was sent” with no evidence to diagnose where the state diverged.
Offline-first checklist
- Explicit action classification.
- Durable local persistence.
- Idempotent mutation IDs.
- Visible pending/failed state.
- Per-domain conflict rules.
- Retry/backoff and replay.
- Attachment lifecycle.
- Observability and support context.
Offline-first becomes valuable when it makes the operating workflow resilient, not when it maximizes the number of screens that happen to render without Wi-Fi.