When we started SomaCare, a telemedicine tool for school nurses, we thought "offline support" was a feature. We would build the app, then add a cache, then show a banner when the network dropped. Two weeks into the first field visit, we threw most of that away.

The nurses we worked with were not occasionally offline. They were occasionally online. Signal came and went with the weather, the time of day and which side of the building they were standing on. An app that treats offline as an error state is an app that is broken most of the day.

The lesson that reshaped the architecture was this: offline-first is a data problem, not a UI problem. The interface follows from decisions about where data lives, who can change it and what happens when two changes disagree.

Start with the source of truth on the device

In SomaCare, the local database is the source of truth for the user in front of the screen. Every read comes from local storage. Every write goes to local storage first. The network is a background process that moves changes between devices and the server when it can.

This single decision removes a whole category of bugs. There are no loading spinners on the critical path, no half-saved forms and no "please try again" after a nurse has typed a careful note about a sick child.

Use an outbox, not a queue of API calls

Our first attempt replayed API calls when the network came back. It failed in every interesting way: calls arrived out of order, duplicated after retries, or referenced records the server had never seen.

What works is an outbox. Each local change is written to the record table and to an outbox table in the same local transaction. A sync worker drains the outbox in order, in small batches, and marks entries as acknowledged only when the server confirms them.

create table outbox (
  id          integer primary key autoincrement,
  entity      text not null,
  entity_id   text not null,
  op          text not null check (op in ('upsert', 'delete')),
  payload     text not null,
  created_at  text not null default (datetime('now')),
  acked_at    text
);

On the server, every write is idempotent and keyed by a client-generated ID, so a retried batch is harmless. On Supabase this means upserts on UUID primary keys, with Row Level Security doing the authorisation work that a custom API would otherwise have to repeat.

Choose conflict policies per table

The question that matters most is also the one most teams avoid: what happens when two people change the same thing while offline?

There is no single answer, so we stopped looking for one. Instead, each table has an explicit policy:

  • Clinical notes are append-only. Nobody edits a note. Corrections are new notes that reference the old one, so there is nothing to conflict.
  • Student profiles use last-writer-wins per field, with a server timestamp and an audit log, because simultaneous edits are rare and low risk.
  • Referral status is a state machine. The server rejects transitions that are invalid from the current state, and the app shows the nurse what changed.

Writing these policies down took an afternoon. Not writing them down had cost us weeks.

Make sync visible, but quiet

Users do not need to understand sync, but they do need to trust it. Each record shows a small, consistent indicator: saved on this device, or synced. A single screen lists anything that is waiting, with the time of the last successful sync. We do not show a red banner when the network drops, because for our users that is simply the weather.

What carries over

You do not need to be building for rural clinics to benefit from this. Trains, lifts, conference Wi-Fi and overloaded mobile networks make every app occasionally offline. If you start from the data model, local source of truth, an outbox and explicit conflict policies, the interface becomes simpler and the app becomes calmer to use.

The network will always be unreliable. The data model is where you decide whether that is your user's problem or yours.