Offline synchronization conflicts begin when two devices hold different temporary truths about the same record. Reconnecting cannot be reduced to uploading the newest-looking JSON or trusting device clocks. The server needs the user’s intent, the version they observed, the fields or operation changed, and a domain policy for merge, rejection, or review.
This guide focuses on conflict decisions and recovery UX. The offline-first PWA patterns guide covers local storage, queues, and service-worker lifecycle; here the subject is versions, commands, merges, deletion, and review across web or mobile clients.
Choose the synchronization unit
Decide whether the client submits whole records, field patches, or semantic commands such as “complete job” and “add quantity.” Commands often preserve intent better than a complete stale snapshot and let the server reapply current business rules.
Every operation needs a unique ID, payload version, actor, tenant, local creation time, ordering, dependencies, and observed server version. Device time can help display context but is not a trustworthy global ordering mechanism.
Use versions and preconditions
Send a version, ETag, or comparable precondition representing what the client read. The server accepts an update only when the expected version still applies or returns a conflict representation with the minimum authorized context.
Update version transactionally with the record and prevent client tampering. Test two simultaneous requests against the same version: one should follow the accepted rule and the other should enter conflict handling.
Separate duplicate delivery from conflict
The same operation retried after a timeout is a duplicate and should return its previous result without repeating work. Two different operations based on the same old version can be a true conflict. Use operation identity for idempotency and record version for concurrency.
Confusing them creates conflict dialogs after routine retry or duplicate side effects. Reject reuse of an operation ID with different content and retain results under a defined policy.
Classify fields by merge safety
Some changes are additive, some are sets, some are exclusive values, and some carry financial, inventory, appointment, or approval risk. Write policies by domain type, not by screen. A note may still be unsafe to merge automatically when meaning or authorship matters.
Last-write-wins is a real policy only if the product accepts loss of the earlier update and can explain it. It is rarely a safe default for money, scarce capacity, or state transitions.
Design transformable commands
“Consume two units in operation X” may reapply safely to current stock where “set stock to eight” cannot. “Complete checklist item Y” is more precise than replacing the entire checklist. The right form follows domain rules.
Version commands as clients evolve. A device offline for a week may submit an old payload. Migrate it when semantics are preserved; otherwise hold it for review rather than dropping user work.
Make server authority explicit
The server owns current authorization, global constraints, balances, and shared reservations. The client can persist intent but cannot promise that a slot, amount, or payment will be accepted. Distinguish “saved on this device” from “accepted by the system.”
Reauthorize at synchronization because membership or role can change while offline. Return stable error codes and only the fields needed to explain resolution. Never expose another user’s private record as conflict evidence.
Build a conflict inbox
Store local operation, permitted current state, differing fields, available actions, creation time, and decision owner. A 409 should move the operation to needs_attention, not delete it from the queue.
Order conflicts by impact and age. A technician may resolve a harmless note while a supervisor owns a financial change. The resolution command must carry a fresh precondition because the record can change again while the dialog is open.
Design understandable resolution UI
Show “your change” and “current state” with domain labels, not raw JSON. Highlight changed facts and server time. Offer only allowed choices: retain current, apply selected change, merge, or create a separate record.
Avoid a generic Overwrite action for money and appointments. Test Arabic RTL, long values, keyboard use, and screen readers. Preserve a support reference without copying sensitive payload into logs.
Treat deletion as a state
A device may modify a record deleted or archived on the server. Retain a tombstone or deletion version long enough for the supported offline window. Decide whether the operation is rejected, restored under authority, or becomes a new record.
An offline client must not resurrect data removed for access or retention reasons. Test account revocation and devices that reconnect later. Deletion permissions should be rechecked like any other command.
Preserve dependency order
Creating a local record, attaching media, and completing it are dependent operations. Use client-stable IDs and a mapping to server IDs. Record dependencies so completion cannot run before creation and children enter a clear state if the parent is rejected.
Persist the queue across application termination. Process independent operations without letting one failure block the world, while preserving order where it changes meaning.
Avoid trusting clocks
Device time can be inaccurate or deliberately changed. Use server receipt time plus record versions or sequences for authoritative order. Preserve original device time for context and timezone display without rewriting it to now.
For out-of-order state events, enforce allowed transitions. A late “started” event should not reopen a completed job. Retain rejected transitions where operational review matters.
Protect local data
Store the minimum required for offline work, isolate accounts and tenants, and lock or clear records after logout or revocation when the device reconnects. Do not promise remote deletion from a device that never returns.
Avoid long-lived credentials and sensitive payloads in diagnostic logs. Encryption helps but does not replace device access and minimization. Test shared devices and successive users. The operational offline-first guide helps choose which workflows justify this exposure.
Test a conflict matrix
Cover two devices changing the same field and separate fields, duplicate retry, different operations from one version, delete versus edit, changed permission, expired session, old application version, schema upgrade with backlog, storage exhaustion, and interrupted processing.
Use slow and flapping networks and terminate the application mid-sync. The interface must not say synced before server acknowledgement. Monitor lost operations, prevented duplicates, oldest queue age, and conflicts by type without logging their sensitive content.
Give support recovery tools
Assign each operation a searchable reference and safe state history. Support should know whether it remained local, arrived, failed, or awaits a decision. Provide controlled diagnostic export where needed and do not make “clear app data” the first response.
Web and PWA development can own the implementation boundary, but product and domain owners decide merge policy. Start with one valuable offline journey, not a claim that the entire system works without connectivity.
Conclusion: preserve intent before choosing a winner
Reliable conflict resolution distinguishes retry from competing change, detects versions, applies domain policy, and retains work until an authorized decision. The last timestamp is not automatically truth. Request an offline conflict design workshop with three realistic cases, decision roles, and local-data boundaries.
