CRDT Explained: How Conflict-Free Data Sync Actually Works

Conflict-free replicated data types are what let two people edit the same document — or the same Kanban board — on two different devices, with no server refereeing who's right. Here's what they are and how the merge actually happens.

The problem: two people, two copies, one truth

The moment more than one device holds a copy of the same data, you have a distributed systems problem. If both copies can be edited independently — including while offline — you eventually need to reconcile them into a single, consistent state. The traditional answer is a central server: every write goes through it, so it can order changes and reject conflicts. That works, but it means the app stops functioning the instant the server is unreachable, and it means the server operator has to be trusted with every byte of your data.

A conflict-free replicated data type (CRDT) is a data structure designed so that any two replicas can be merged automatically, with a mathematically guaranteed outcome — no server, and no manual conflict resolution required.

How the merge actually happens

Instead of storing a document as one blob of text or JSON, a CRDT tracks changes as a set of operations, each tagged with metadata that makes ordering and merging unambiguous — typically a unique ID per client plus a logical clock. When two replicas exchange their operation history, each one can independently compute the same merged result, because the merge function is commutative, associative, and idempotent: it doesn't matter what order the operations arrive in, or whether the same operation arrives twice — the final state converges to the same value on every replica.

Concretely, for something like a Kanban card's title, that usually means representing text as a sequence of uniquely-identified characters rather than a plain string, and representing a list of cards as an ordered set with stable identities rather than an array of indexes. Move a card, and every replica agrees on where it landed, even if two people dragged different cards into the same column at the same moment.

CRDTs vs. operational transformation

Google Docs popularized real-time collaborative editing using operational transformation (OT), an older technique that also resolves concurrent edits — but by transforming incoming operations against a central, ordered history, which generally requires a server to arbitrate. CRDTs solve a similar problem without that requirement: because merges are guaranteed to converge regardless of order, two peers can sync directly with each other, or sync opportunistically whenever they happen to be online together, with no authority deciding who goes first.

Where CRDTs show up

They're the foundation of most "local-first" software — apps that treat your device as the primary copy of your data, with sync as an optional, best-effort layer rather than a requirement. Yjs and Automerge are the two most widely used general-purpose CRDT libraries in the JavaScript ecosystem, and both are used in production note-taking apps, whiteboards, and collaborative editors.

How Driftboard uses one

Every Driftboard workspace is a single Yjs document. Lists, cards, checklists, comments, and labels are all Yjs data types nested inside it, which is what lets two peers edit different cards — or the same card — at the same time and have both sets of changes land cleanly. Two things sit on either side of that document:

• y-indexeddb persists the document to your browser or Electron app's local storage, so the workspace is fully usable with zero network connectivity, ever.
• y-webrtc broadcasts document updates directly to any other peer holding the same workspace, over an encrypted WebRTC data channel, whenever both of you happen to be online at the same time.

See how the WebRTC side of that actually connects two peers for the transport-layer details.

What CRDTs don't give you