Offline-first, described as what happens to one work order

Offline-first is an architecture, not a feature flag. The device keeps its own copy of the data a technician needs, the app always reads from that copy, and every change is written locally and appended to a queue that drains whenever a connection exists. Nothing on screen waits.

The distinction from an app that merely tolerates a dropout is that there is no online path to fall back from. An offline mode means 2 code paths, and the rare one is untested. Offline-first has 1, and the network is a background process that reconciles.

One job, opened and closed with no bars

A technician drops into a crawlspace at 09:40 with no signal and comes out at 10:25 with the job finished. What the app did:

1. Opened the job from the local store. Job, customer, site, equipment and its last 3 visits arrived in the 06:30 sync, so the screen renders instantly.
2. Recorded arrival. A timestamp row appends to the write queue with a local id, plus a monotonic reading so a clock change cannot rewrite it.
3. Captured the work. Checklist answers, parts and notes each append their own queued write; the local store updates immediately.
4. Captured evidence. 14 photos and a signature go to device storage, their uploads joining a separate media queue — a 4 MB photo and a 200-byte status change must not share a lane.
5. Marked the job complete. Validation runs against local data, so every completion rule must be answerable on the device.
6. Reconciled at 10:31 on the drive out. The queue drains in order, the server accepts each write by client id, the cursor advances. The only step that touched a network.

The 4 parts, and what each one owns

The last row carries most of the design work, and it is a business decision: status, notes, parts, time and photos each need a different rule. That belongs in a merge policy written field by field. How much to pre-cache is a sizing question, in how much data a truck day needs on the device.

The 2 things it can never do

It cannot show data that was never synced. A job added at 11:00 while out of coverage, or equipment history for a site off the morning route, is simply absent. Pre-caching therefore becomes a product decision about which jobs, how much history and which price-book slices ride along — and route shape changes the risk, one reason route density is the unit a pest schedule optimises.

And it cannot finish a large upload on demand. Tapping save writes the photo locally and enqueues it; the bytes leave when there is bandwidth and battery, which on a truck day can be hours. When it becomes days, the diagnosis is Tuesday's photos are still uploading on Friday. Which images are required is the photo set a completed job should carry.

Offline-first does not mean the work order syncs quickly. It means the technician never finds out whether it did.

What the platform gives you, and what it does not

SQLite in write-ahead logging mode is the ordinary local store. Its documentation states that in WAL mode readers do not block writers and a writer does not block readers, with only 1 writer at a time, and that durability after power loss depends on the synchronous setting — the log syncs on each commit only when PRAGMA synchronous is FULL.

What no platform decides is which records ride along, which completion rules can be answered locally, and who wins when both sides edited a field. Time capture shows why: every segment is a queued write with a clock caveat, so a field timesheet records its capture source rather than a total.

Built, this is unglamorous and testable: a schema, a queue, a cursor, a merge table. We scope it under AI agents and automation alongside dispatch logic, with the habits in AI agents in production. It sits in the technician's phone, inside our field service work.

• offline
• mobile apps
• sync
• definitions