Skip to main content
Mobile

Offline-first sync: decide what happens when the network returns.

Sync rules are product behaviour. Write down which version wins for each kind of conflict, and let users see what has reached the server. Here's how to design an app that keeps working in basements, warehouses, and the middle of nowhere.

By Anvexis Stack Engineering8 min read

Why offline is a design decision, not a feature

Most apps treat being offline as an error: show a spinner, then a message, then let the user try again later. That works when connections are reliable. For a technician in a basement, a picker in a steel-roofed warehouse, or a driver on a rural road, it means the app fails exactly when it's needed.

Offline-first apps reverse the assumption. The device holds the data the user needs, every action is saved locally first, and synchronization happens in the background whenever a connection exists. The influential Ink & Switch essay on local-first software puts it in two of its seven ideals: no spinners, and the network is optionalSource [1]. Its authors point out that when the server holds the primary copy, every change and many look-ups need a round trip, which is why cloud apps so often feel slowSource [1].

Record operations, not snapshots

The simplest sync approach sends whole records: here's the order as it looks on my device now. It fails as soon as two people change the same record, because one version overwrites the other and information disappears without anyone noticing.

A sturdier approach records operations: add two units, change the delivery date, mark the task done. Operations carry intent, so the server can often apply both people's changes. Two pickers each adding stock produce the correct total; two snapshots would lose one of the additions.

For data that many people edit at once, such as shared notes or checklists, CRDTs go further. They are data structures designed to be multi-user from the ground up, so replicas can merge without a central refereeSource [1]. They're powerful, but most business apps get far with plain operations and clear server-side rules.

Ordering, retries, and duplicates

Operations must be applied in the right order and exactly once. Devices queue operations with sequence numbers, retry when a send fails, and attach a unique identifier, generated on the device, to each one. The server remembers which identifiers it has already applied, so a retry after a dropped response doesn't apply the same change twice.

This is the same idempotency idea that keeps integrations safe, and it matters even more on mobile, where connections drop in the middle of requests all the time. Our article on idempotency explained with coffee covers the server side in detail.

The offline design checklist

  • Classify every operation: safe offline, online-only, or needs confirmation
  • Generate IDs on the client so retries are idempotent
  • Define a conflict rule per type of data
  • Retry with exponential backoff and cap the attempts
  • Show pending, synced, and failed states in the interface
  • Give support staff a view of stuck operations

Let the platform carry the queue

A sync queue that only runs while the app is open will lose work when the user swipes it away. Use the platform's durable background work. On Android, WorkManager stores scheduled work in an internal database and reschedules it across app restarts and device rebootsSource [2]. It also supports constraints, such as only running on an unmetered network, and configurable exponential backoff when work failsSource [2].

On the web, be careful. The Background Synchronization API lets a service worker defer tasks until the user has a stable connection, but MDN marks it as limited availability because it doesn't work in some of the most widely used browsersSource [3]. Treat it as a bonus: retry from the page whenever it's open, and use background sync where available to finish the job sooner.

Conflict rules are business rules

“Last write wins” is a decision, not a default. For a delivery status it may be right; for a stock count it silently destroys data. When two technicians update the same job, should the latest note win, should both notes be kept, or should a supervisor decide? The answer depends on the data, and the people who own the process should choose it.

Write the rules down per type of data and build them into the sync engine. Simple fields can often take the latest change; quantities can usually merge; prices, credit limits, and approvals should usually defer to the server, with the device's change turned into a request rather than a fact.

Example conflict rules

DataRuleWhy
Job notesKeep both, newest firstLosing a technician's note loses information
Stock countedMerge as quantities added or removedSnapshots would drop one count
Delivery statusLatest change winsOnly the current state matters
Prices and discountsServer wins; device change becomes a requestCommercial decisions need approval
Signatures and photosNever overwrite; store every versionThey are evidence

Photos, signatures, and large files

Field apps live on attachments: proof-of-delivery photos, signatures, scanned forms, meter readings with a picture as evidence. These are big, slow to upload, and the first thing to fail on a weak connection. Treat them as their own queue, separate from the small data changes, so a stuck photo upload never blocks a completed job from syncing.

Upload files in resumable chunks where the platform allows it, compress images on the device to a sensible size, and link each file to its record by the client-generated ID rather than waiting for the server's. Keep the local copy until the server confirms it has the file, then clean up to protect the device's storage. And show attachment status separately in the interface: “job synced, 2 photos still uploading” is a far more useful message than a single spinning icon.

Show users the truth

Users need to know whether their work is safe. A small indicator showing saved on this device, waiting to sync, or synced removes most of the anxiety, and most of the duplicate entries that come with it. When a conflict needs a decision, show both versions clearly and explain why.

Hiding sync status to keep the interface clean is a false economy. People who don't trust the app keep paper backups, call the office to confirm, or enter the same data twice, which creates exactly the conflicts you were trying to avoid.

Keep the device's data small and fresh

Syncing everything to every device is slow, wastes storage, and increases the damage if a phone is lost. Sync only what each user needs: their assignments, the relevant products and customers, and recent history. Fetch changes incrementally rather than downloading full datasets each time.

Encrypt data on the device, require a login or device lock to open the app, and support remote wiping for lost devices. Local-first doesn't mean less secure; the Ink & Switch authors list security and privacy by default among their idealsSource [1].

Plan schema changes across app versions

Users don't all update their apps on the same day, so the server will receive changes from old and new versions at the same time. Design the sync API so older clients keep working while newer ones use new fields, and migrate the data stored on devices carefully when the app updates. A version number on every request makes it possible to handle each client correctly.

Test upgrades with pending changes still in the queue. An update that discards unsynced work is one of the fastest ways to lose users' trust.

Test like the network hates you

Offline behaviour must be tested deliberately: airplane mode for hours, connections that drop mid-request, two devices editing the same record, low battery, and an app closed while changes are still pending. Automate these scenarios where possible, because they're exactly the cases manual testing misses.

Include the slow-but-online case. A connection that technically works but takes thirty seconds per request is harder to handle than a clean offline state, and it's what users in the field actually experience most.

Test time, too. Device clocks drift, users change time zones, and some phones are simply set to the wrong date. Never use the device clock alone to decide which change came last; record it, but let the server assign the authoritative order when operations arrive. A conflict rule that depends on a wrong clock will pick the wrong winner, quietly, for weeks.

Monitor sync in production

Once the app is live, watch the sync system as closely as any other service: queue sizes per device, failure rates, conflict counts by type of data, and how long changes take to arrive. Unusual spikes reveal bugs, network problems at specific sites, or conflict rules that need refining, often before users report anything.

If you're adding offline support to an existing app, start with the workflow where losing work hurts most, such as completed jobs, signatures, or stock counts. Proving the design there surfaces the hard questions early. Our offline-first architecture work and Odoo mobile apps follow exactly this order.

Questions to answer before you build

  • Which data must be available offline, and for how long?
  • Which actions can complete offline, and which need a connection?
  • What happens when two people change the same thing?
  • How long might a device stay offline?
  • How will users see what's pending, and who sees stuck operations?

Frequently asked questions

What is the difference between offline-capable and offline-first?
An offline-capable app copes with short drops, usually by queueing a request or two. An offline-first app saves everything locally first and treats the network as optional, so it works the same in a basement as in the officeSource [1].
Does offline-first work in a web app?
Yes, using local storage such as IndexedDB and a service worker. Just don't rely only on the Background Synchronization API, which some major browsers don't support; retry whenever the page is open as wellSource [3].
How do we stop duplicate records when a sync is retried?
Give every operation an ID generated on the device and have the server ignore IDs it has already applied. That makes retries safe however many times they happen.
Should we use CRDTs?
For collaborative data that many people edit at once, they're worth consideringSource [1]. For most business apps, operations with clear per-entity conflict rules on the server are simpler and easier to reason about.

Sources

  1. [1]Local-first software: You own your data, in spite of the cloud (opens in a new tab)Ink & Switch (Kleppmann, Wiggins, van Hardenberg, McGranaghan), April 2019
  2. [2]Task scheduling (WorkManager) (opens in a new tab)Android Developers
  3. [3]Background Synchronization API (opens in a new tab)MDN Web Docs

Written by Anvexis Stack

We build Odoo, AI, web, and cloud systems for growing companies, and we write about the patterns we use. This is engineering guidance, not a product guarantee: check vendor details for your version before you decide. Last reviewed .