Design an offline sync engine

Requirements exploration

Most web apps work like a phone call: the user clicks, the app asks the server, the server answers, the screen updates. Every action costs a round trip of 100 to 300 ms on a good connection and fails completely on a bad one.

A sync engine flips this. The app keeps a copy of the user's data in a database inside the browser. The UI reads only from that local copy and writes only to it, so every action takes a few milliseconds. In the background, a sync loop sends local changes up to the server and brings other people's changes down.

That one sentence hides most of the hard problems in distributed systems: two copies of the same data that drift apart, writes that cross on the wire, a server that rejects a change the user already saw succeed, and a browser that may delete your database when the disk is full. So the first five minutes of the interview are about scope. The answers change the design more than in almost any other problem.

Questions to ask first

• Is the server the source of truth, or are the clients equal peers? Peer-to-peer (true local-first, no authority) pushes you toward CRDTs everywhere. A central server that can say no is much simpler, and it's what Linear, Replicache, and PowerSync all assume.
• How long can a user be offline? Minutes (a tunnel) and two weeks (a field engineer) need different answers for queue size, conflict handling, and how old a sync cursor can get before we start over.
• How much data does one user see? 20,000 issues at about 1.5 KB each is 30 MB of JSON. That fits in the browser. 2 million rows doesn't, so we'd need partial sync from day one.
• What kind of edits? Setting a field (status, assignee) is easy to merge. Free text in a long description edited by two people at once needs a text CRDT. Moving money needs the server to decide.
• Are there business rules the client can't check alone? "Only admins can close a project", "an issue number is unique per team". These decide where conflicts are resolved.
• Which browsers and devices? Desktop Chrome only, or Safari and mobile too? Storage limits, eviction rules, and worker support differ.
• Can users share a computer? Data at rest on a library PC is a security question we must answer before we store anything.
• Is this one app or a platform? Here it's a platform, so the engine can't know what an issue is. Apps register their tables and their mutations.

Functional requirements

• The UI reads from a local database through live queries: a query that re-runs and re-renders whenever the rows it depends on change, from any source.
• Every write applies to the local database first and shows on screen in the same frame. The write is queued and sent to the server later.
• The queue survives reloads, crashes, and closing the laptop. Nothing the user saw saved is ever lost silently.
• Changes made by other users and other devices arrive in the background and appear without a refresh.
• The app works fully offline for reads and writes, for at least 7 days, and catches up when the network returns.
• Conflicts resolve automatically by sensible rules. When the server rejects a change, the user is told what happened and the screen shows the true state.
• Several tabs of the app stay consistent and don't fight over the database.
• A sync status the user can trust: saved, syncing, offline with N changes waiting, or an error.

Non-functional requirements

Out of scope, and why

• Live character-by-character co-editing of long documents. That's a text CRDT or OT system (see the Google Docs guide). We'll show where one plugs in, but the engine is about records.
• Server storage design. We define what the server must provide (a change log, a cursor, idempotent mutations), not how its database shards.
• Peer-to-peer sync without a server. We assume one authoritative server.
• Offline login. The user must have signed in on this device before. We cache the session, we don't invent auth.

What makes this hard

A normal app has one copy of the truth: the server. A sync engine has at least three: the server, the local database on each device, and the pending changes that one device made but the server hasn't confirmed. Every hard part of this design comes from keeping those copies honest with each other. Five traits drive every decision that follows.

• Two sources of truth, one authority. The UI trusts the local database, but the server has the final word. The engine must show the local answer now and quietly correct it later, without the user noticing anything except when it truly matters.
• Writes cross on the wire. While your "set status to Done" is in flight, a teammate's "assign to Priya" for the same issue arrives. Each side saw a different order of events. The engine must reach the same final state on every device anyway.
• Time is long and unreliable. A mutation may be queued for a week. The server's code, the schema, and the user's permissions may all change before it's sent. The network can drop mid-request, so the client often doesn't know whether a push landed.
• The browser is a hostile place to keep a database. Storage is quota-limited and can be evicted. Every open tab is a separate process that may try to write. A tab can be killed at any moment, including halfway through applying a batch of changes.
• It must be reusable. The engine can't know what an issue is. Apps give it a schema and named mutations; the engine handles storage, queueing, sync, and rebasing for any of them.

Here's a concrete morning that touches every trait. Ana opens the tracker on a train with three tabs open. She closes 12 issues and edits two descriptions while offline for 40 minutes. Meanwhile her teammate Ben, online, moves four of those issues to another project, and an admin removes Ana from one private project.

When Ana's train reaches the station, her laptop has a pending queue of 14 mutations, a sync cursor that's 40 minutes old, and data she's no longer allowed to see. Within a second or two, all three tabs must show the same correct state. Her 14 changes must land exactly once, Ben's moves must not be undone, and the private project's issues must vanish from her disk.

The core loop: the local database drives the UI

The first decision shapes everything else: where does the UI read from, and where does a write go first? Let's start naive and see where it breaks.

Naive version: every component fetches from the API, and every write is a POST that the UI waits for. On a 200 ms connection, closing 12 issues in a row costs 12 spinners; on a train it costs 12 error toasts.

Adding optimistic updates helps the online case: the UI changes first and rolls back if the request fails. But the optimistic state lives in memory. Reload the tab while offline and the 12 changes are gone, and the next screen you open has no data to show at all.

The four moves of the loop

1. Read. A component runs a live query, such as "open issues in project 7, sorted by priority". The engine runs it against the local database and re-runs it when any table it read from changes.
2. Write. The component calls a named mutation such as closeIssue({ id: 42 }). The engine runs the app's mutator code against the local database in one transaction, and in the same transaction appends { id, name, args } to the pending queue. Live queries re-run; the screen updates in the same frame.
3. Push. The sync loop sends pending mutations to the server in order. The server runs its own version of each mutator, with full permission checks, and records which mutation ids it has applied.
4. Pull. The client asks "what changed since my cursor?". The server returns a delta and a new cursor. The engine applies the delta, drops the pending mutations the server has confirmed, and replays the rest on top. That last step is the rebase, and it gets its own chapter.

Notice that the UI never talks to the network. That's the boundary that makes the engine reusable and testable: components only know live queries and mutations, and the sync loop only knows tables, mutations, and cursors. Here's what an app team writes to use the engine.

const engine = createSyncEngine({
  name: "tracker",
  schemaVersion: 4,
  tables: {
    issue: { key: "id", indexes: ["projectId", "status", "updatedAt"] },
    comment: { key: "id", indexes: ["issueId"] },
  },
  mutators: {
    async closeIssue(tx, args: { id: string }) {
      const issue = await tx.get("issue", args.id);
      if (!issue) return; // deleted elsewhere: do nothing
      await tx.put("issue", { ...issue, status: "done" });
    },
    async addComment(tx, args: { id: string; issueId: string; body: string }) {
      await tx.put("comment", { ...args, createdAt: tx.now() });
    },
  },
});

// In a component:
const issues = useLiveQuery((q) =>
  q.table("issue").where("projectId", "p7").where("status", "!=", "done").orderBy("priority"));
await engine.mutate.closeIssue({ id: "i42" });

Choosing the local database

The engine needs a database in the browser that holds 30 MB or more, survives restarts, supports indexes for live queries, and writes many rows atomically. localStorage is out on every count: it's synchronous (it blocks the main thread), holds about 5 MiB per origin, stores only strings, and has no transactions. The real candidates are IndexedDB and SQLite compiled to WebAssembly. The IndexedDB and Client storage lessons cover the APIs; here we only weigh them for a sync engine.

The one IndexedDB trap that breaks sync engines

An IndexedDB transaction commits on its own as soon as there are no pending requests and control returns to the event loop. If a mutator does await fetch(...) or even await sleep(0) in the middle of a transaction, the transaction commits early and the next write throws TransactionInactiveError.

For a sync engine this means two rules. Mutators must be pure local code: they read and write the database and nothing else. And the row writes plus the queue append must happen in the same transaction, so a crash can never leave a changed row without its queued mutation, or the reverse.

Quotas, eviction, and asking to persist

Browsers give each origin a generous quota (the most it may store). Chrome and Edge allow up to 60% of total disk. Firefox allows 10% of disk or 10 GiB per site, whichever is smaller, in its default "best-effort" mode. Safari (macOS 14, iOS 17 and later) allows about 60% of disk for the browser app.

Size is rarely the problem. Eviction is: under storage pressure, browsers delete whole origins, least recently used first, unless the origin has persistent storage. Safari also deletes script-written data for sites the user hasn't interacted with in the last 7 days of browser use, when tracking prevention is on. A Home Screen web app keeps its own counter, which resets each time it is opened.

For a cache, eviction is fine. For a sync engine it can destroy unsent work, so the engine does three things. First, it calls navigator.storage.persist() after the user shows intent (signs in, or turns on offline mode). Chrome grants or denies this silently based on engagement, Firefox asks the user, and Safari grants it by heuristics such as running as a Home Screen web app.

Persistence protects against eviction under storage pressure, but Safari's 7-day rule may still apply, so the engine can't rely on it alone. Second, it checks navigator.storage.estimate() and warns before the quota fills. Third, it treats the pending queue as the precious part: if the queue is non-empty and the user is online, it pushes promptly instead of letting the queue sit.

async function ensureDurableStorage() {
  if (!navigator.storage?.persist) return "unsupported";
  if (await navigator.storage.persisted()) return "persisted";
  const granted = await navigator.storage.persist();
  return granted ? "persisted" : "best-effort";
}

// On boot: a client id in IndexedDB that's missing means the data was
// evicted or cleared. Start a fresh bootstrap and tell the user if
// the last session had unsent changes (tracked server-side by client id).
const meta = await store.get("meta", "client");
if (!meta) await bootstrapFromSnapshot();

The mutation queue

Every local write leaves a record in a queue, and the queue is what the server eventually sees. Two questions shape it: what goes into each entry, and how we make sure each entry is applied on the server exactly once, in order, even when requests time out and tabs crash.

Mutation ids and exactly-once

Each device gets a random clientId the first time it boots, stored in the local database. Each mutation gets the next integer for that client: 1, 2, 3, and so on, so the pair (clientId, mutationId) is unique forever. The server stores one number per client: lastMutationId, the highest one it has processed. That makes its push handler simple and safe to repeat.

for (const m of push.mutations) {
  await db.transaction(async (tx) => {
    const last = await tx.lastMutationId(push.clientId); // 0 if new
    if (m.id <= last) return;            // duplicate: already applied
    if (m.id > last + 1) throw new OutOfOrder(); // a gap: client must resend
    try {
      await serverMutators[m.name](tx, m.args, { userId });
    } catch (err) {
      // Rejected by a rule: record it, apply nothing, but still advance.
      await tx.recordRejection(push.clientId, m.id, String(err));
    }
    await tx.setLastMutationId(push.clientId, m.id);
  });
}

Two details matter. First, the lastMutationId update is in the same server transaction as the mutation's writes, so either both happen or neither does. Second, a rejected mutation still advances the counter; otherwise one mutation that always fails (a deleted project, a lost permission) would block every mutation behind it forever. This is the poison message problem, and the fix is to reject loudly but move on.

Retries, batching, and a queue that survives reloads

• Durable. The queue is a table in the local database, written in the same transaction as the mutator's row changes. A reload, a crash, or a closed laptop loses nothing.
• Ordered. Only one push is in flight per client at a time, and it always starts from the oldest unconfirmed mutation. Order matters: createIssue must land before addComment on that issue.
• Batched. A push sends up to 100 mutations or about 100 KB, whichever comes first. After a week offline, 5,000 mutations go up in about 50 requests, not 5,000.
• Retried with backoff. A network error or a 5xx retries after 1 s, 2 s, 4 s, up to 60 s, with random jitter so 10,000 clients coming back after an outage don't all retry in the same second (see the Retries and backoff lesson). A 401 (an expired session) stops the loop and asks the user to sign in; the other error answers are listed with the protocol.
• Confirmed by pull, not by push. A successful push response only means "received". The client drops a mutation from its queue when a pull reports lastMutationId at or above it, because that pull also carries the server state that mutation produced. This keeps the rebase consistent.

The timeout case shows why ids matter. The client sends mutations 15 to 20, and the server applies them, but the response is lost when the train enters a tunnel. The client doesn't know whether they landed, so it sends 15 to 20 again. The server sees lastMutationId = 20 and skips all six; without ids, Ana would get six duplicate comments.

The pull side: cursors, deltas, and tombstones

Push sends our changes up. Pull answers the opposite question: what changed on the server since I last asked? The naive answer, "give me everything", means a 30 MB response every few seconds for 20,000 issues. The next idea is timestamps ("give me rows with updatedAt after my last pull time"), which is subtly wrong in a way worth seeing.

Suppose the client pulls at 10:00:00.500 and remembers that time. A server transaction that started at 10:00:00.400 writes a row with updatedAt = 10:00:00.400 but commits at 10:00:00.700. The pull at .500 couldn't see it (not committed), and the next pull asks for rows after .500, so the row is missed forever. Clock skew between servers and many writes in the same millisecond cause the same bug.

What a pull returns

{
  "cookie": "w7:v18342",
  "lastMutationId": 35,
  "rejected": [{ "id": 32, "reason": "forbidden" }],
  "patch": [
    { "op": "put", "table": "issue", "id": "i42", "value": { "status": "todo", "projectId": "p9", "v": 18339 } },
    { "op": "del", "table": "comment", "id": "c901" },
    { "op": "put", "table": "issue", "id": "i77", "value": { "title": "Fix login", "v": 18342 } }
  ],
  "hasMore": false
}

• Puts carry whole rows, not field diffs. A put is idempotent: applying it twice gives the same result, so a retried pull is harmless.
• Deletes are tombstones. When a row is deleted, the server keeps a small record (table, id, version) in the log. Without it, the client can't tell "deleted" from "unchanged", and the row lives on its disk forever.
• Pages. A large delta comes in pages of about 1,000 operations with hasMore: true. The client applies each page in its own transaction and only stores the new cookie after the page is applied, so a crash mid-sync just repeats a page.
• Rejections ride along, so the client can tell the user which changes didn't make it.

When the cursor is too old

The server can't keep tombstones forever. Say it keeps 30 days of change log, and a laptop that's been closed for 45 days sends a cookie the server can no longer answer from the log. The server replies with a reset: a clear operation followed by a full snapshot (the same one a new device downloads). The client applies it into fresh tables and swaps them in.

Crucially, the client keeps its pending queue and replays it on top, just like any other rebase. Mutations that no longer make sense (an issue deleted 40 days ago) become no-ops in the mutator or get rejected by the server, and the user is told.

When does the client pull? On boot, on a server "poke" (a tiny WebSocket or SSE message that says "workspace w7 changed, pull now", with no data in it), after each successful push, and every 60 seconds as a safety net. Pokes keep the server simple: there's one code path for getting data (pull), and the real-time channel only says when to use it.

Rebasing: server changes arrive while local work is pending

This is the heart of the engine. A pull brings server state, but the local database already contains the effects of mutations the server hasn't seen yet. Writing the patch straight over local rows would wipe out pending work: Ana closes issue 42, a pull arrives with Ben's version of issue 42 (still open, now assigned to him), and her close flickers away even though it's still in the queue. Ignoring the patch for rows with pending changes is just as wrong: she'd never see Ben's assignment.

Replicache's documentation describes the answer clearly. The client does not try to merge the patch into local state. Hidden from the app, it rewinds to the last state it got from the server, applies the patch to reach the server's current state, then replays the still-pending mutations on top, and reveals the result atomically. It's the same idea as git rebase: your unpushed commits are reapplied on top of the new upstream.

A worked example

The vote shows why named mutations matter. A raw diff would have said votes = 4, and replaying it would erase Chen's vote. The mutator addVote says +1, so replay gives 5, which is what the server will compute too. When the server later processes m36 and m37, the next pull reports lastMutationId: 37 with the same values, the queue empties, and nothing on screen moves.

How to rewind cheaply

Two refinements keep rebases cheap. If the queue is empty, skip rewind and replay: just apply the patch, which is the common case. And replay runs in a worker, not on the main thread, so 200 pending mutations replaying after a long offline stretch never block typing.

Why not CRDTs for everything?

CRDTs (conflict-free replicated data types, see the CRDTs lesson) merge any two replicas without a server, by design. That's powerful and also a cost: every data type must be a CRDT, documents carry metadata, and there's no natural place for a rule like "only admins can close a project", because every replica must accept every change.

With a central server, the rebase model gets convergence for free: every client ends up at "server state plus my pending mutations", and the server state is one ordered history. Business rules live in server mutators, which is simpler and safer for apps made of records (issues, tasks, settings). Use a CRDT for the one place that needs it, such as a long description edited by two people at once, and store it as a field the server merges.

Conflict resolution

Rebasing tells us how changes get ordered: the server's order wins, and local work is replayed on top. It doesn't tell us what each mutation should do when it lands on data someone else changed. That's conflict resolution, and the Conflict resolution lesson covers the general strategies. Here we pick per kind of data, because one rule for everything is always wrong somewhere.

Take a real partition (two copies that can't talk to each other for a while). Ana, offline on the train, sets issue 42's priority to High and its title to "Safari bug". Ben, online, sets the same issue's priority to Low and its assignee to himself. Ana reconnects 40 minutes later: what should issue 42 look like?

Business rules the client can't decide

• Ids. Clients create rows with random UUIDs (crypto.randomUUID()), so two offline clients never collide. Human numbers like ENG-1042 are assigned by the server mutator; the client shows a placeholder such as ENG-? until the pull brings the real one.
• Workflow. "An issue with open blockers can't be closed." The client mutator checks what it knows; the server mutator checks the truth and rejects if a blocker appeared meanwhile.
• Permissions. Always the server's call. The client may hide a button, but the server mutator is the check that counts.
• Counters and sets. addVote, addLabel, removeLabel are written as operations, so concurrent ones combine instead of overwriting.

When to show the user a conflict

Most conflicts should resolve quietly; asking users to merge priorities is noise. Two cases deserve a visible notice. The first is a rejected mutation: the user saw something succeed that didn't, so say which change and why ("Couldn't close ENG-1042: it has an open blocker"), with a link to the issue.

The second is a lost edit to a field with real effort in it, like a 300-word description written offline that lost to a newer edit. For those, the mutation carries the version the user started from (baseVersion). If the server sees the field changed since then, it keeps the winner but saves the losing text as a conflict copy, and the UI says "Your offline edit was saved as a copy" with a button to compare. Nothing typed is ever thrown away.

Partial sync and the first load

So far each client has "the data". Which data? Syncing the whole company database to every laptop fails three ways at once: it's too big (a company with 300 teams has millions of rows), it's too slow to download, and it leaks: a contractor's browser would hold HR's private projects. The engine needs a way to say "this client holds this subset" and to change the subset when access changes.

When permissions remove data

An admin removes Ana from the private project p9. Hiding it in the UI isn't enough, because the rows are still on her disk. The server records which scopes each client holds, so when membership changes, the next pull includes a dropScope operation for project:p9.

The client deletes every row tagged with that scope in one transaction, removes pending mutations that touch only those rows (the server would reject them anyway), and tells the user their access changed. Every row carries its scope as an indexed field, so this delete is one index range scan, not a full table walk.

Bootstrapping a new device

A new laptop has nothing. Pulling 20,000 issues through the delta path (1,000 operations per page) means 20 round trips and a lot of per-row bookkeeping. Instead, the server builds a snapshot per scope: a gzipped file of newline-delimited JSON rows plus the cookie it corresponds to, rebuilt every few minutes and served from a CDN. 30 MB of JSON compresses to roughly 4 to 6 MB.

1. Fetch the snapshot as a stream in the sync worker and decompress it with DecompressionStream("gzip") (or let the server send Content-Encoding: gzip).
2. Parse line by line and insert in batches of about 2,000 rows per transaction, so memory stays flat and progress is visible.
3. Load the user's own open issues first (a small, separate snapshot), so the first screen shows in about a second while the rest streams in.
4. When the snapshot is in, set the cookie to the snapshot's cookie and pull normally. The delta covers anything that changed while downloading.

Schema migrations on the client

A server-only app changes its database schema once, on the server. A sync engine has thousands of copies of the schema, one per device, and some of them were last opened three weeks ago. Every schema change now has three audiences: the server database, the local database on every client, and the mutations sitting in queues that were created under the old schema.

Concrete case: version 4 of the tracker splits issue.assignee (one user id) into issue.assignees (a list). A laptop on version 3 has 20,000 issues stored the old way and 40 queued assignIssue({ id, userId }) mutations. It loads the new code tomorrow morning.

Upgrades with several tabs open

IndexedDB runs schema changes inside onupgradeneeded when a page opens the database with a higher version number. If another tab still holds a connection at the old version, the upgrade is blocked until that tab closes it. Old tabs get a versionchange event; the engine must close its connection there and show "A new version is available, reload to continue", or the new tab waits forever. Never leave an old tab writing to a database whose shape changed under it.

Old mutations and old clients

• Mutations are versioned like an API. The queued assignIssue from v3 has args { id, userId }. The server keeps accepting it and translates it to assignees: [userId]. A changed shape gets a new name or a v: 2 field; old ones are supported until clients older than the support window (say 30 days) are forced to update.
• Each push says who's talking. The push request carries schemaVersion: 3. The server can answer with a clear error such as { "error": "client_too_old", "minVersion": 4 }, and the client then pushes nothing, updates its code, and retries, so no mutation is lost.
• Pulls are shaped for the client's version. The server can send v3 clients a single assignee (the first in the list) until they upgrade. That's extra server work, so keep the window short.
• Client mutators are versioned too. During replay after an upgrade, a v3 mutation runs through a small adapter that converts its args before the v4 mutator sees them.

Many tabs, one database

Power users keep five tabs of a tracker open, and every tab loads the engine. If each one ran its own sync loop, we'd get five WebSocket connections per user, five pulls for every poke, and five pushers reading the same queue. Mutation ids keep the pushes safe from duplicates, but two pushers can still send 41 to 45 and 43 to 48 at the same moment, and the server sees gaps and retries.

The Cross-tab sync lesson covers the browser APIs; here's how a sync engine uses them.

const changes = new BroadcastChannel("tracker-sync");
let syncLoop: SyncLoop | null = null; // set only in the leader

navigator.locks.request("tracker-sync-leader", async () => {
  status.set({ role: "leader" });
  syncLoop = startSyncLoop({ onApplied: (tables) => changes.postMessage({ type: "applied", tables }) });
  await new Promise(() => {}); // hold the lock for this tab's lifetime
});

changes.onmessage = (e) => {
  if (e.data.type === "applied" || e.data.type === "local-write") liveQueries.invalidate(e.data.tables);
  if (e.data.type === "local-write") syncLoop?.schedulePush();
};

A follower tab's write runs its mutator in its own IndexedDB transaction. Inside that transaction it reads and increments meta.nextMutationId, so ids stay unique and in order across tabs with no extra locking. Then it posts local-write on the channel: the leader schedules a push, and the other followers re-run their live queries.

When the leader finishes a rebase, it posts applied with the tables it touched. All tabs share one clientId, because they share one queue and one local database. (Replicache instead gives each tab its own client id inside a shared "client group"; either works as long as ids are ordered per client.)

Connectivity and the sync status

The engine needs to know when to try the network. The obvious signal is navigator.onLine with its online and offline events, but it's a weak signal. false reliably means "no network at all", while true only means the device is connected to some network: hotel Wi-Fi with a login page, a phone with one bar, or a VPN that's down all report true. So the engine treats navigator.onLine as a hint and lets real requests decide.

• Offline when navigator.onLine is false, or after 2 consecutive failed requests (network error or timeout). A request timeout is 15 s, enforced with AbortController.
• Try now on the online event, on visibilitychange to visible (the laptop lid just opened), on a poke from the socket, and whenever a local write happens.
• Back off between attempts while offline or failing: 1 s, 2 s, 4 s, capped at 60 s, with jitter. Any trigger above resets the wait and tries at once, so a user who opens the lid doesn't wait a minute.
• Stay quiet when hidden. A hidden tab drops its poll interval from 60 s to 5 minutes and keeps the socket only if it's the leader.

What about syncing after the user closes every tab? The Background Sync API lets a service worker get a sync event when connectivity returns, even with no tab open, so it could push the queue. It's only available in Chromium-based browsers (Chrome, Edge, and others), not in Firefox or Safari (see the Background sync lesson).

We use it as a bonus where it exists. The service worker requests the same Web Lock as the tabs with ifAvailable: true, so if a tab is already leading it simply stops; otherwise it opens the IndexedDB queue and pushes. Everywhere else, the queue waits until the app is opened again, and nothing is lost because it's durable.

A status the user can trust

Users of an offline-capable app have one worry: "is my work saved?" The status indicator answers it, so it must be honest. It derives from two facts the engine knows exactly: the number of pending mutations and the state of the sync loop.

For screen readers, the status text sits in a polite live region (role="status"), and it only announces transitions that matter: going offline, coming back with changes synced, and errors. Announcing every 1-second sync would make the app unusable with a screen reader.

The status can also drive a beforeunload warning. While the queue is non-empty and the browser lacks Background Sync, the engine adds the listener, so closing the tab shows the browser's generic "leave site?" prompt; it removes the listener once the queue drains, because a listener that's always attached can keep pages out of the back/forward cache in some browsers. The work is safe on disk either way: the prompt only warns that teammates won't see it until the app is opened again.

Architecture, data model, and the sync protocol

The core loop drew the logical picture; now let's place each piece on a thread. The rule that sets the boundaries: the UI thread renders and handles input, and nothing slow runs there. Storage, sync, rebase, and snapshot parsing run in a dedicated worker, one per tab, and only the leader tab's worker talks to the network.

Why put the store in a worker if IndexedDB is already asynchronous? Because the slow part isn't IndexedDB's I/O, it's our JavaScript around it: structured cloning 1,000 rows, replaying 200 mutators, re-running 30 live queries after a rebase, parsing a 30 MB snapshot. Each of those can take 50 to 500 ms on a mid-range laptop.

In a worker they cost nothing on the main thread, and the UI gets small result diffs over postMessage. The cost is one hop of latency, about 1 ms, which still fits the 16 ms budget for a local write.

Why does the engine client keep a copy of the latest results? So components render synchronously from memory instead of waiting on the worker every time they render. After a mutation, the worker applies it and the affected queries post new results back within a few milliseconds, typically inside the same frame. If an app needs a write reflected in the very next paint, such as text in an input, that state stays in the component until the mutation settles, just like any controlled input.

Data model and the sync protocol

The local database holds two kinds of tables. App tables hold rows exactly as the app defined them, plus two engine fields: scope (for dropping data when access changes) and v (the server version that last wrote it). Engine tables hold everything about sync. Keeping them apart means an app can't break sync by accident, and the engine can wipe app data while keeping the queue.

type Meta = {
  clientId: string;          // random UUID, created on first boot
  cookie: string | null;     // opaque pull cursor from the server
  nextMutationId: number;    // incremented inside each mutation's transaction
  schemaVersion: number;     // local schema, for migrations
  scopes: string[];          // e.g. ["team:eng", "team:design"]
  userId: string;            // owner of this data; checked on every boot
};

type PendingMutation = {
  id: number;                // per client: 1, 2, 3...
  name: string;              // "closeIssue"
  args: unknown;             // JSON, validated by the mutator
  mutatorVersion: number;    // for adapters after upgrades
  createdAt: number;         // for the dev panel, never for conflicts
};

type UndoEntry = { mutationId: number; table: string; key: string; before: unknown | null };
type Rejection = { mutationId: number; reason: string; seenByUser: boolean };

The protocol is two HTTP endpoints, one snapshot URL, and one tiny socket message. HTTP for push and pull keeps them easy to retry, cache-proof (both are POST with Cache-Control: no-store), and observable in any proxy. The socket never carries data, so losing it only delays sync until the next poll.

POST /sync/push
Content-Type: application/json
Authorization: Bearer <token>

{ "clientId": "c-7f3a", "schemaVersion": 4,
  "mutations": [
    { "id": 36, "name": "closeIssue", "args": { "id": "i42" }, "v": 1 },
    { "id": 37, "name": "addVote", "args": { "issueId": "i42" }, "v": 1 } ] }

HTTP/1.1 200 OK
{ "lastMutationId": 37 }

POST /sync/pull   { "clientId": "c-7f3a", "cookie": "w7:v18342", "scopes": ["team:eng"], "schemaVersion": 4 }
  -> 200 { cookie, lastMutationId, rejected, patch, hasMore }
  -> 200 { reset: true, snapshot: "https://cdn.example.com/snap/team-eng/v18900.ndjson.gz" }

WS  /sync/poke     server -> client: { "type": "poke", "scope": "team:eng" }

GET /snap/team-eng/v18900.ndjson.gz   (immutable, cacheable for a year)

Errors: 401 sign in again | 409 { "error": "out_of_order", "expected": 36 }
        400 { "error": "client_too_old", "minVersion": 4 } | 429/5xx retry with backoff

Note the 409 out_of_order answer. If the server ever sees mutation 38 when it expected 36, something went wrong on the client (a bug, or restored storage), so the server says which id it expects and the client pushes from there. If the client no longer has 36, it can't fill the gap: it reports the lost range, resets the counter with the server, and records the incident in the dev panel and logs. That should be rare enough to page someone.

Security, debugging, and testing

Three topics that interviewers love as follow-ups, because each one is easy to forget and painful to retrofit: what happens to the data on a shared computer, how anyone debugs a sync bug on a user's laptop, and how you test a system whose bugs only appear when messages arrive in an unlucky order.

Data at rest and signing out

IndexedDB and OPFS files are stored unencrypted inside the browser profile. Disk encryption protects a stolen, powered-off laptop, but anyone who can use the OS account (a family PC, a library computer) can open the profile and read 30 MB of company data.

Encrypting rows with a Web Crypto key sounds like the fix, but the key must live somewhere the offline app can reach, which is the same profile. It raises the bar only if the key comes from the server after sign-in and is kept in memory, which gives up offline cold starts. So the engine's real defenses are policy and cleanup:

• Ask at sign-in. "Keep data on this device for offline use?" Off means in-memory mode: same engine, no persistence. Admins can force it off for their organization.
• Sign-out clears everything. First try to push the queue; if changes are pending, say so: "3 changes haven't synced. Sign out anyway?" Then broadcast signout so other tabs close their connections, call indexedDB.deleteDatabase, clear caches, and have the sign-out response send Clear-Site-Data: "storage" as a backstop in browsers that support it.
• Check ownership on boot. meta.userId must match the signed-in user. If it doesn't, the previous user's data is wiped before anything renders.
• XSS is the bigger risk. Any script running on the origin can read the whole database. A strict Content Security Policy and sanitized rich text matter more here than in a server-rendered app.

Seeing inside the engine

Sync bugs are reported as "my change disappeared" with no steps to reproduce. So the engine ships with a dev panel (behind a keyboard shortcut, also enabled for support staff) that shows the client id, leader status, cookie, last pull and push times, the pending queue with names, args, and age, recent rejections, and storage usage. One button exports all of it as JSON for a bug report.

In production, the engine reports a few metrics: queue length at p95, time from local write to confirmation, rebase duration, rejection rate per mutation name, resets per day, and how often a boot finds its database missing (eviction). A rising rejection rate for one mutation after a deploy usually means the client and server mutators disagree.

Deterministic simulation

Unit tests check mutators, but they can't catch the bug where a pull lands between a push and its retry while a second tab writes. For that we run the whole system in one process: three simulated clients, an in-memory server, and a fake network that drops, delays, duplicates, and reorders messages, all driven by one seeded random generator and a fake clock.

Each run performs random user actions, random partitions, and random tab crashes, then heals the network, lets everything settle, and checks invariants. A failing seed replays the exact same run, every time.

for (let seed = 1; seed <= 5000; seed++) {
  const sim = createSim({ seed, clients: 3, server: memoryServer() });
  for (let step = 0; step < 300; step++) {
    sim.randomAction({
      mutate: 0.5, partition: 0.1, heal: 0.1,
      crashTab: 0.05, deliver: 0.25, // deliver may drop, dup, or reorder
    });
  }
  await sim.healAndSettle();
  for (const c of sim.clients) {
    assert.deepEqual(c.store.snapshot(), sim.server.viewFor(c.userId), `seed ${seed}`);
    assert.equal(c.queue.length, 0, `seed ${seed}: queue drained`);
  }
  assert.ok(sim.server.eachMutationAppliedOnce(), `seed ${seed}`);
}

Running it in the interview

This problem is huge, and the risk is spending 30 minutes on IndexedDB APIs and never reaching rebasing. Interviewers for this question want to see that you understand the three copies of the data and how they converge. Storage details are supporting cast. Here's a plan for 45 minutes.

Say the trade-offs as you go, briefly: "named mutations cost us duplicate mutator code, but intent is what makes replay correct". And reach for one concrete number per decision: 30 MB for 20,000 issues, 100 mutations per push batch, 30 days of tombstones. Numbers show you've thought about scale without a lecture.

Follow-ups to expect