Design a Collaborative Editor (Google Docs)

1Requirements

2Back-of-envelope estimation

3API design

4High-level design

The naive approach fails immediately: if Alice inserts at position 5 while Bob deletes at position 2, applying their raw operations in different orders yields different documents on each replica. Every collaborative editor is an answer to this concurrency problem, and the two established answers are operational transformation (OT) and conflict-free replicated data types (CRDTs).

OT, the Google Docs approach, keeps operations position-based (insert 'x' at 5) and transforms them against concurrent operations before applying: if Bob's delete at 2 arrives first, Alice's insert shifts to position 4. OT is dramatically simpler when a central server serializes all operations into one canonical order: each client tracks the last server revision it has seen, sends ops against that revision, and the server transforms incoming ops over anything it accepted since. Clients symmetrically transform their unacknowledged local ops over incoming remote ops.

CRDTs instead give every character a permanent unique identity (say, an author-counter pair plus a reference to its left neighbor), so operations commute by construction and no transformation or central sequencer is needed. This makes offline merge and peer-to-peer sync natural, at the price of per-character metadata and tombstones for deleted text. Modern implementations (Yjs, Automerge) compress the overhead well enough that CRDTs are now the default for new projects, while OT survives in systems that already have a central server and want minimal payloads.

The serving architecture: each document is owned by exactly one WebSocket server (route by hashing document id at a connection gateway), which holds the document's hot state, orders or merges ops, appends them to a persisted op log, and broadcasts to subscribers. Snapshots every N ops bound recovery and history-replay time. If the owner dies, another server reloads snapshot plus op-log tail and clients reconnect with their last acked revision.

Presence (cursors, selections, who's online) rides the same WebSocket but is ephemeral: throttled, broadcast, never written to the log. Cursor positions must be mapped through the same transform/identity machinery as text, otherwise remote cursors drift as text changes around them. With CRDTs this is elegant: a cursor is just a reference to a character id, so it survives any remote edit automatically.

5Data model

6Deep dives

7Rapid implementation: build the MVP

Theory is table stakes. Here is how you would stand up a working version fast, on a budget, with the core algorithm in real code.

1. 01Create the docs, ops (PK doc_id + rev), and snapshots tables in Postgres.
2. 02Define the op format as JSON: {retain n, insert 'text', delete n} segments over the whole document, plus baseRev and author.
3. 03Implement transform(opA, opB) for insert/insert, insert/delete, and delete/delete cases with unit tests asserting both application orders converge.
4. 04Build the WebSocket server: on connect, send snapshot plus ops since the client's revision; on op receipt, transform over concurrent ops, INSERT the op row, ack the author with the new rev, broadcast to others.
5. 05Build the client sync loop: apply local edits to the textarea immediately, keep one op in flight, compose further edits into a buffer, transform pending ops over incoming remote ops.
6. 06Map remote cursors: broadcast {pos} presence messages at most 10/sec and shift each remote cursor through the same transform as text.
7. 07Add snapshotting every 200 ops and a /history page that replays ops from the nearest snapshot with a revision slider.
8. 08Torture test: two headless clients firing random concurrent edits for 10,000 ops, assert final texts are byte-identical.

type Op =
  | { type: "insert"; pos: number; text: string; author: string }
  | { type: "delete"; pos: number; len: number; author: string };

// Transform opA so it applies correctly AFTER opB has been applied.
export function transform(a: Op, b: Op): Op {
  if (b.type === "insert") {
    const shift = b.text.length;
    if (a.type === "insert") {
      // Tie at same position: lower author id goes first (deterministic on all replicas)
      const aFirst = a.pos < b.pos || (a.pos === b.pos && a.author < b.author);
      return aFirst ? a : { ...a, pos: a.pos + shift };
    }
    if (a.pos >= b.pos) return { ...a, pos: a.pos + shift };
    if (a.pos + a.len <= b.pos) return a;
    return { ...a, len: a.len + shift }; // b inserted inside a's delete range
  }
  // b is a delete
  const bEnd = b.pos + b.len;
  if (a.type === "insert") {
    if (a.pos <= b.pos) return a;
    if (a.pos >= bEnd) return { ...a, pos: a.pos - b.len };
    return { ...a, pos: b.pos }; // a's insertion point was deleted
  }
  const aEnd = a.pos + a.len;
  if (aEnd <= b.pos) return a;
  if (a.pos >= bEnd) return { ...a, pos: a.pos - b.len };
  const overlap = Math.min(aEnd, bEnd) - Math.max(a.pos, b.pos);
  return { ...a, pos: Math.min(a.pos, b.pos), len: a.len - overlap };
}

async function handleClientOp(doc: DocState, client: Client, msg: { baseRev: number; op: Op }) {
  let op = msg.op;
  // Transform over every op accepted since the client's base revision
  const concurrent = doc.log.slice(msg.baseRev); // log[i] produced rev i+1
  for (const prior of concurrent) op = transform(op, prior.op);

  const rev = doc.log.length + 1;
  doc.content = applyOp(doc.content, op);
  doc.log.push({ rev, op, author: client.userId });
  await db.query(
    "INSERT INTO ops (doc_id, rev, author_id, op_json) VALUES ($1, $2, $3, $4)",
    [doc.id, rev, client.userId, JSON.stringify(op)]
  );

  client.send({ type: "ack", rev });                       // author advances baseRev
  for (const peer of doc.clients) {
    if (peer !== client) peer.send({ type: "op", rev, op }); // others transform locally
  }
  if (rev % 200 === 0) await saveSnapshot(doc.id, rev, doc.content);
}

class ClientSync {
  rev = 0;                    // last server revision synced
  inflight: Op | null = null; // sent, awaiting ack
  buffer: Op[] = [];          // local edits composed while waiting

  localEdit(op: Op) {
    applyToEditor(op);        // optimistic: typing never waits on the network
    this.buffer.push(op);
    this.flush();
  }
  private flush() {
    if (this.inflight || this.buffer.length === 0) return;
    this.inflight = this.buffer.shift()!;
    ws.send(JSON.stringify({ type: "op", baseRev: this.rev, op: this.inflight }));
  }
  onServerMessage(msg: any) {
    if (msg.type === "ack") { this.rev = msg.rev; this.inflight = null; this.flush(); return; }
    // Remote op: transform it over our pending ops, and our pending ops over it
    let remote: Op = msg.op;
    const pending = [this.inflight, ...this.buffer].filter((o): o is Op => o !== null);
    for (let i = 0; i < pending.length; i++) {
      const mine = pending[i];
      pending[i] = transform(mine, remote);
      remote = transform(remote, mine);
    }
    if (this.inflight) this.inflight = pending[0];
    this.buffer = pending.slice(this.inflight ? 1 : 0);
    applyToEditor(remote);
    this.rev = msg.rev;
  }
}