Offline-first mobile sync without surprise conflicts

Offline capability changes the consistency contract of an application. A screen can no longer assume that the server is immediately reachable or that the local copy is current. Before adding a sync queue, decide which user actions remain safe when disconnected.

Persist user intent locally

Store a durable operation or draft before telling the user it is saved. Include a local identifier, operation type, base version, and creation time. Do not store credentials or sensitive content without considering device encryption, shared-device behavior, and retention after sign-out.

Make replay safe

Each operation should have a stable idempotency key so a timeout and retry do not create duplicates. The server should validate authorization at replay time; access may have changed since the operation was queued. Retry transient failures with backoff and surface a clear state for validation failures that require user attention.

Define conflict behavior by data type

“Last write wins” is easy to implement but can erase a meaningful edit. It may be acceptable for a preference; it is often wrong for a shared task or a financial record. Use version numbers or ETags to detect concurrent edits. Then choose a merge, a conflict copy, a domain-specific resolution, or a prompt for the user.

Make sync status understandable

Show whether a change is local, pending, synced, or blocked. Preserve local work if authentication expires or the server rejects an update. Give the user a retry or export path for recoverable failures rather than deleting the queue silently.

• Test process termination during a sync attempt.
• Test duplicate operations and out-of-order responses.
• Test sign-out, account changes, and revoked access.
• Measure queue growth and define a retention limit.

Offline-first is most effective when it is selective. Keep the operations that genuinely need to work offline small, durable, observable, and governed by explicit conflict rules.