Offline-First: Building for Real Network Conditions

A lot of software is built and tested in an office with good, stable wifi, then deployed to people in vehicles, store rooms, clinics, farms and building sites. The gap between those two environments is where a surprising amount of software quietly fails.

It usually doesn't fail loudly. It fails as a spinner that never resolves, a form that loses what someone typed, or a sync that silently duplicates yesterday's records. Designing for that from the start costs far less than retrofitting it.

Intermittent is harder than offline

Fully offline is honestly the easy case — you know where you stand. The difficult case is a connection that's technically present but effectively unusable: a request that will succeed in forty seconds, or never, and you can't tell which.

Naive code handles this badly. It sends a request, waits on a default timeout that's far too long, and leaves the user staring at a frozen screen with no idea whether their work was saved.

The connection being "up" tells you nothing useful. Design for requests that hang, arrive twice, or arrive out of order.

The local store is the source of truth

This is the central shift, and everything else follows from it.

In a conventional app, the server holds the truth and the device asks for it. In an offline-first app, the device writes to its own local database first and treats that as real. Syncing to the server is a separate background concern.

The immediate benefit is that the interface never waits on the network to feel responsive. A user taps save, the record is saved — locally, definitely, immediately — and the app moves on. Whether it has reached the server yet is a different question, and one the user mostly shouldn't have to think about.

What that changes in practice

• Every record needs an identifier the device can generate itself, without asking the server. You can't wait for a server-assigned ID to know what you just created.
• Every record needs a sync state: local only, in flight, confirmed, or failed.
• Reads come from the local store, not from a network call, so screens work identically online and off.

The sync queue

Changes made offline go into an ordered queue of pending operations, drained when a connection is available. A few things make the difference between a queue that works and one that corrupts data:

• Order matters. If someone creates a record and then edits it, replaying those out of order produces nonsense. Preserve sequence per record.
• Retries must back off. A device that retries a failing request every second on a weak connection will flatten its own battery and make the connection worse for everything else.
• Failures must be visible somewhere. An operation that has failed twenty times needs to surface to someone, not retry silently forever.
• The queue must survive being killed. Phones close apps aggressively. If the queue lives only in memory, work disappears.

Idempotency is not optional

The classic data-corruption bug: the device sends a change, the server processes it, the response is lost on the way back. The device assumes failure and retries. Now there are two records.

The fix is for the client to attach a unique key to each operation and for the server to recognise a key it has already handled and return the original result rather than doing the work again. This is a small amount of code and it prevents an entire category of duplicates that are miserable to clean up after the fact.

Conflicts: decide the rule in advance

If two people edit the same record while offline, someone's version has to win. What you must not do is leave that undefined and discover the answer in production.

The options, roughly in order of cost:

• Last write wins. Simple, and genuinely fine when records have a natural single owner. Silently loses data when they don't.
• Field-level merge. If two people changed different fields, keep both. Handles most real conflicts well.
• Flag for human resolution. Correct where the data really matters — stock counts, clinical records, money — and worth the interface it requires.

Choose per data type, not once for the whole app. A user's own draft notes and a shared inventory count deserve different answers.

Tell the user the truth, quietly

People tolerate being offline. What they don't tolerate is not knowing whether their work is safe.

• Show a persistent, undramatic indicator of connection state. Not a modal — a modal blocking work because the network dipped is worse than the network dipping.
• Show per-item state where it matters: saved on device, syncing, synced.
• Never show a success message that means "sent to the server" when what you mean is "saved locally". Be accurate about which one happened.

Test it properly

Airplane mode is a start, but it only tests clean offline — the easy case. Also test:

• A connection that drops mid-request, not between requests.
• Very high latency, so requests succeed but slowly.
• The app being force-closed with items still queued.
• Two devices editing the same record while both offline, then both reconnecting.
• A device that's been offline for a week, so the queue is large and the server data has moved on.

That last one catches more bugs than the rest combined, and it's the one almost nobody runs before launch.

It's a design decision, not a feature

Offline support is not something you bolt on near the end. It changes how records are identified, how state is stored, how the interface reports progress, and what the server accepts. Deciding early is inexpensive; deciding late means rewriting the data layer of a working app.

So the question to ask at the start isn't "will it work offline?" It's "where will people actually be standing when they use this?" — and then building for that place rather than for the office.

If your team works somewhere the signal doesn't reach, tell us where and what they're doing, and we'll tell you what it takes to keep working there.