State & ArchitectureExperimental

Local-First Sync & CRDTs

Mental Model

Local-first apps read and write against local IndexedDB or OPFS at 0 ms, treating the server as a sync peer rather than a gatekeeper. Conflict-free Replicated Data Types (CRDTs) tag operations with (clientId, logicalClock) so concurrent offline edits converge to the exact same state regardless of arrival order.

Interactive Simulator

Sync Architecture: Server-First LWW vs Local-First CRDT

Compare naive timestamp Last-Write-Wins overwrites against commutative CRDT state convergence.

Lines of Code
Before
5
After
3
Reflows / Browser Cost
Before
Silent offline data loss
After
0ms local read/write latency
BeforeServer-First + Wall-Clock LWW
// Offline client B overwrites client A's edits on reconnect
await fetch('/doc/1', {
  method: 'PUT',
  body: JSON.stringify({ content: fullText, updatedAt: Date.now() })
});
Lines: 5Reflows: Silent offline data lossDependencies: Clock skew breaks ordering

Whichever laptop reconnects last wipes out the other user's offline paragraphs.

After (Native)Local-First CRDT (IndexedDB + Delta Merge)
// Every edit writes locally at 0ms with a unique (clientId, lamportClock)
ydoc.transact(() => ytext.insert(cursor, 'hello'));
// Reconnect exchanges stateVector diffs; both peers converge identically
Lines: 3Reflows: 0ms local read/write latencyDependencies: Commutative + idempotent merge

Concurrent offline edits merge deterministically in any arrival order.

Under the Hood

Unlike Optimistic UI, where the server remains judge and jury and failed mutations roll back, a CRDT works like an append-only ledger with mathematical commutativity (merge(A, B) === merge(B, A)). Paired with a Service Worker for offline asset booting, the client never blocks on a round-trip.

  1. Local persistence: Edits commit immediately to IndexedDB or Origin Private File System (OPFS) in sub-millisecond transactions.
  2. Causal IDs: Each character or map key receives a unique Lamport/Hybrid Logical Clock (clock, clientId) tuple, immune to skewed laptop system clocks.
  3. State-vector sync: On reconnect, peers exchange compact version vectors and stream only missing operations, converging identically with zero central lock.
JS
// Commutative LWW-Register merge: order-independent convergence
function mergeRegister(local, remote) {
  if (remote.hlc > local.hlc) return remote;
  if (remote.hlc === local.hlc && remote.clientId > local.clientId) return remote;
  return local;
}

Problem Genealogy

  • 2006 (Operational Transformation, Google Docs): Transformed concurrent cursor indices on a central server, notorious for subtle convergence bugs off-server.
  • 2011 (Shapiro et al. CRDTs): Proved algebraic semilattice properties guaranteeing lock-free peer convergence.
  • 2019+ (Local-First Software, Ink & Switch, Yjs, Automerge): Combined CRDTs with IndexedDB/SQLite-Wasm to bring sub-frame responsiveness to collaborative web apps.

Production Pitfalls

Production Pitfall
  • Unbounded tombstone growth: Deleted characters in sequence CRDTs stay as invisible tombstones so concurrent edits know where they sat; without snapshot compaction, a 10 KB note can bloat to 50 MB of history.
  • Wall-clock Date.now() tie-breakers: Relying on a user's system clock for Last-Write-Wins lets a laptop with a clock set to 2099 win every merge forever.
When Not to Use
  • When not to use CRDTs: For strict financial ledgers, inventory counts, or unique-username claims where two offline writes cannot both succeed, use server-authoritative transactions instead.

Connections & Logical Next Steps

State & ArchitectureLocal-First Sync & CRDTs

Seen in Architecture Autopsies

Mechanical Comparisons