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
| Data | Rule | Why |
|---|---|---|
| Job notes | Keep both, newest first | Losing a technician's note loses information |
| Stock counted | Merge as quantities added or removed | Snapshots would drop one count |
| Delivery status | Latest change wins | Only the current state matters |
| Prices and discounts | Server wins; device change becomes a request | Commercial decisions need approval |
| Signatures and photos | Never overwrite; store every version | They 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?
Does offline-first work in a web app?
How do we stop duplicate records when a sync is retried?
Should we use CRDTs?
Sources
- [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]Task scheduling (WorkManager) (opens in a new tab)Android Developers
- [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 .
Keep exploring
Offline-first sync
Offline-first mobile architecture: local databases, operation queues, conflict resolution, retries, and clear sync status for users.
MobileOdoo mobile apps
Custom mobile apps for Odoo: barcode warehouse scanning, delivery and proof of delivery, field service, and offline sync.
InsightsIdempotency explained with coffee
Why retried API calls create duplicate orders, and how idempotency keys make integrations safe, explained with a coffee order.
Next step
Got a tangled system? Let's untangle it together.
Thirty minutes with an engineer, no slide deck required. You'll leave with a clearer picture, whether or not we work together.
