Offline-first: a clinical app that works with zero signal.

The hard part of an offline app isn’t the UI. It’s everything you take for granted when there’s a server in reach: who is this user, where does the data live, is it safe, and how do days of edits reconcile without corrupting a patient’s record.

The client, a US-based IT partner to health services providers (now part of Netsmart), needed a documentation app that simply assumed there was no network and treated connectivity as a bonus. Below is how we answered each of those questions, and the two open-source libraries that came out of it.

The instant a user can open the app offline, the server is out of the loop, so something on the device has to establish that they’re authorized. The naive answer, caching a token or a key, is exactly what has bitten Android historically: on a booted or rooted device with the right tools, anything written to storage can be read back, key included.

So we decided to store no key. We made an App PIN part of authentication, and, as the next section shows, that same PIN doubles as the encryption key. Nothing persisted to the device reveals it.

We reached for redux-persist with SQLite as the backing store, and hit a compatibility gap between redux-persist and react-native-sqlite-storage. Rather than wedge around it, we wrote the bridge ourselves and open-sourced it.

1// SQLite as the backing store for the whole Redux tree.2const storage = SQLiteStorage(SQLite, {3  name: 'clinical-state.db',4  location: 'default',5});6 7const persistConfig = {8  key: 'root',9  storage,                       // ← our redux-persist ↔ SQLite bridge10  transforms: [encryptState()],  // every value encrypted before it hits disk11};12 13const store = createStore(14  persistReducer(persistConfig, rootReducer),15  applyMiddleware(offline(offlineConfig)),16);

We never persist the PIN. Instead the PIN derives the encryption key. We keep a single static, known key-value pair (a sentinel) encrypted in storage. On unlock, we decrypt the sentinel with the user-supplied key. If it comes back as the value we expect, the PIN was correct: the user is authenticated and we now hold the key to decrypt the rest of the state. One operation, two guarantees.

1// The PIN is never stored, anywhere. It derives the key, and nothing else.2const deriveKey = (pin: string, salt: string) =>3  pbkdf2Sync(pin, salt, 100_000, 32, 'sha256');4 5// One static sentinel proves the PIN: only the correct key decrypts it back to6// the value we expect, which authenticates the user AND unlocks the store.7async function unlock(pin: string): Promise<SessionKey | null> {8  const key = deriveKey(pin, await getUserSalt());9  const decoded = await tryDecrypt(await readSentinel(), key);10  return decoded === SENTINEL ? key : null;   // wrong PIN ⇒ garbage ⇒ null11}12 13// That same session key transparently encrypts the persisted state.14const encryptState = () =>15  createTransform(16    (state) => aes256.encrypt(JSON.stringify(state), sessionKey),17    (blob) => JSON.parse(aes256.decrypt(blob, sessionKey)),18  );

We used redux-offline to keep the store consistent offline and replay queued mutations on reconnect. But its outbox is a plain FIFO. It has no smart queue for duplicate resource references or the merging and re-ordering that go with them. Replayed naively, dependent operations can land out of order and corrupt a record.

1// redux-offline ships a FIFO outbox. It can't tell that three edits hit the2// same note, or that a `create` must land before its `update`. Replayed3// naively, that corrupts the record. Our smart queue dedupes by resource and4// preserves causal order.5function enqueue(outbox: Mutation[], next: Mutation): Mutation[] {6  const i = outbox.findIndex((m) => m.resourceId === next.resourceId);7 8  if (i !== -1 && mergeable(outbox[i], next)) {9    const merged = merge(outbox[i], next);            // one network call, not two10    return outbox.map((m, k) => (k === i ? merged : m));11  }12 13  return [...outbox, next];   // otherwise append, never reorder dependents14}

• Became a core contributor to redux-offline with the smart-queue work.
• Released a new open-source library, redux-persist-sqlite-storage.
• Delivered an offline-first app with HIPAA-compliant, per-user encryption, with no key on disk.

For a clinician on a home visit, offline is the normal case. Building for it forces you to answer the questions online apps get to skip: identity, storage, encryption, reconciliation. Answer them well and the network becomes a detail. The app just works, and the data shows up safely the moment it can.