NOTE 01 · 18 Oct 2026
The write is the easy part
Most forms assume the network is present. A clinician taps save, a spinner appears, and the record either lands or it does not. In a rural PHC, that assumption is the bug. The connection can disappear for an hour in the middle of an intake, and the clinician still has to finish the consultation.
SwasthyaSetu started from that constraint: the write must succeed locally before anyone asks the network for permission.
Write locally first
The intake form writes to IndexedDB through Dexie before it renders a success state. The record has a stable idempotency key, a status and an attempt count. The UI never waits on a request it cannot make.
The queue is deliberately boring. One object store, ordered by creation time, drained oldest-first. The complexity belongs in the server contract, not in a clever client abstraction.
type OutboxEvent = {
id: string; // stable idempotency key
type: "referral.created";
payload: ReferralDraft;
attempts: number;
createdAt: number;
};
export async function enqueue(event: OutboxEvent) {
await db.outbox.put({ ...event, status: "queued" });
}
export async function drain() {
const pending = await db.outbox
.where("status")
.equals("queued")
.sortBy("createdAt");
for (const event of pending) {
await db.outbox.update(event.id, { status: "syncing" });
try {
await api.post("/events", event, {
headers: { "Idempotency-Key": event.id },
});
await db.outbox.update(event.id, { status: "synced" });
} catch {
await db.outbox.update(event.id, {
status: "queued",
attempts: event.attempts + 1,
});
break; // preserve order; retry from here on reconnect
}
}
}Idempotency is the contract
A retry is not an edge case; it is the normal path. The client may send the same event twice because the response was lost, the tab was closed, or the connection dropped after the server committed. The server has to make the second delivery harmless.
Every event carries a stable key. The API records processed keys and returns the original result on a replay instead of creating a duplicate referral. The client can retry aggressively without turning a flaky network into duplicate clinical records.
- Generate the key once, on the client, before the first attempt.
- Deduplicate on the server, not only in memory.
- Return the same result for a replay so the client can converge.
- Surface duplicate counts; silent deduplication hides sync bugs.
Conflicts are domain decisions
Last-write-wins is convenient for a settings page and unacceptable for a referral. If two facilities update the same patient record, the system cannot pick a timestamp and call it truth. The resolution has to encode the domain: who is allowed to transition which state, and what evidence is required.
The referral lifecycle is an explicit nine-state machine. Every transition writes an immutable audit event. When identity is uncertain, the system surfaces candidates for a human to confirm rather than silently merging two patients.
What I would test next
The current queue handles the common partition-and-reconnect path. The next honest step is a sync simulator in CI that injects reordered events, repeated deliveries and partial failures, then asserts the referral state and audit trail after convergence.
- Property-based tests for event ordering and idempotency.
- A partition matrix covering offline writes on both sides of a transition.
- Sync metrics: queue age, retry count and time-to-convergence.
Offline-first is not a cache. It is a different answer to the question of where the truth lives.