← CatZep/Engineering Guides/System Design/Media & Collaboration

Designing Collaborative Editing

A system design interview guide to building a Google-Docs-style editor where many people type into the same document at the same time and every screen ends up showing exactly the same text.

Real-time collaborative editing looks like magic the first time you see two cursors moving in the same paragraph, but underneath it is one of the cleaner distributed-systems problems you will be asked to design. The single hard requirement is convergence: no matter who typed what, in what order, or on which flaky network, every copy of the document must end up identical. That sounds obvious until you notice that two people can edit the same character position at literally the same moment, and there is no global clock that says which one happened first. This guide builds up the design from that core problem, walks through the two dominant approaches (Operational Transformation and CRDTs), covers the sync architecture that ties clients together, and then handles the practical parts an interviewer will push on: cursors, offline edits, and the tradeoffs between the approaches.

Concepts to understand first

Each definition includes a concrete example and the condition under which the mechanism is useful. You can read this guide without opening another guide.

1. Requirements and Clarifying Questions

• What is being edited? Rich text documents [yes]; spreadsheets and drawings share the ideas but not the details.
• How many editors per document? Usually 1–5; allow up to about 100 active editors, more as viewers.
• Offline editing? Yes, with merge on reconnect.
• Cursors and presence? Yes.
• Version history? Yes, browse and restore earlier versions.

2. Back-of-the-Envelope Estimation

Two lessons. First, the op log grows by terabytes a day, so you must snapshot and compact: store a full snapshot every so often and keep only recent ops hot. Second, the load is spread over millions of small documents, each needing only a few ops per second. That is why one server can own each document: shard by doc_id, not by user. A single very popular document is the hard case, which is why products cap simultaneous editors and turn extra users into read-only viewers.

3. API and Data Model

GET  /v1/docs/{doc_id}                 -> { snapshot, snapshot_seq }   # open a doc
WS   /v1/docs/{doc_id}/live             # persistent connection
  client -> server  { "type": "op", "base_seq": 1041, "op": {...}, "client_op_id": "c7-18" }
  server -> client  { "type": "ack", "client_op_id": "c7-18", "seq": 1043 }
  server -> client  { "type": "op", "seq": 1044, "op": {...} }
  both ways         { "type": "presence", "cursor": 212, "selection": [212, 220] }
GET  /v1/docs/{doc_id}/ops?since=1041   # catch up after reconnect

documents   (doc_id PK, owner, title, created_at, acl)
op_log      (doc_id, seq, author, client_op_id, op_blob, ts)   PRIMARY KEY (doc_id, seq)
snapshots   (doc_id, seq, content_blob)                        PRIMARY KEY (doc_id, seq)
-- open = latest snapshot + ops after snapshot.seq
-- client_op_id makes a resent op idempotent

4. The Core Problem

The document is shared mutable state, and several clients hold their own copy of it. Each client edits its local copy instantly — you cannot wait for a network round trip before showing the user the letter they just typed, or the editor feels broken. That means edits happen optimistically and locally, and only afterwards travel to everyone else. The moment you allow that, you have admitted concurrency: two clients can make edits that neither has seen yet, and those edits can touch the same region of the document.

The trap is to think of an edit as "the new text." If Alice replaces the whole document with her version and Bob replaces it with his, the last write wins and one person's work silently vanishes. The fix is to represent each change as a small, position-aware operation — "insert the character X at position 5," "delete the character at position 0" — rather than a whole-document snapshot. Operations are tiny, they can be ordered and replayed, and they describe intent rather than result. But operations alone are not enough, because a position like "5" means different things on two copies that have already diverged. Resolving that mismatch is the entire subject of the next two sections.

5. Operational Transformation

Operational Transformation (OT) is the older and most battle-tested approach, and it is what classic Google Docs is built on. The idea is to keep editing in terms of operations against integer positions, but to transform each incoming operation so it accounts for the concurrent operations the receiver has already applied. If Bob deleted a character near the start of the document, then Alice's "insert at position 5" needs to become "insert at position 4" before Bob applies it, because his copy is now one character shorter. The transform function adjusts the indices so that both sides converge on the same final text and so that each person's original intention is preserved.

The transformation rules are deceptively subtle. There is a small matrix of cases — insert against insert, insert against delete, delete against insert, delete against delete — and each must be defined so that applying the transformed operations in any order yields the same result. Getting these rules provably correct is famously error-prone; several published OT algorithms were later found to have edge cases that failed to converge. The practical consequence is that OT almost always relies on a central server to impose a total order on operations. The server decides the canonical sequence, and clients transform their pending local operations against the server's sequence as it streams back to them. This sidesteps the hardest multi-party transformation cases by reducing every client's job to "reconcile my local edits against one authoritative stream."

# transform op A so it can apply after concurrent op B
function transform(a, b):
  a = copy(a)                    # never mutate the original op
  if a.type == INSERT and b.type == INSERT:
    if b.pos < a.pos or (b.pos == a.pos and b.site < a.site):
      a.pos += 1                 # b inserted before a, shift right
  if a.type == INSERT and b.type == DELETE:
    if b.pos < a.pos:
      a.pos -= 1                 # b removed a char before a
  # ... delete-vs-insert and delete-vs-delete cases ...
  return a

6. CRDTs

CRDTs have merge/delivery rules designed for convergence. State-based merge is associative, commutative, and idempotent; operation-based designs may require causal delivery or other prerequisites. A grow-only character union cannot implement deletion by itself.

Text sequence CRDT families differ: Logoot/LSEQ use position identifiers; RGA uses predecessor-linked elements; Yjs/Automerge have their own compact structures and causal protocols. They are not all variable-length digit lists sorted the same way. A toy tuple (path,site,counter) also needs a dense allocation scheme between full identifiers: if concurrent IDs share a path, path-only midpoint allocation may not fit between them.

Deleting creates a stable removal/tombstone effect so replaying an old add cannot resurrect text. Safe tombstone collection requires replica/version knowledge or an explicit offline-expiry/resync policy. Site/counter identities must survive restart or use new incarnations. Convergence does not guarantee natural text interleaving or author intention. Use a reviewed library and test its offline/history/access model instead of building a text CRDT from the diagram alone.

7. Central Server vs Peer-to-Peer

Whichever convergence strategy you pick, you still have to decide how operations physically get from one client to another. The two ends of the spectrum are a central sequencing server and a true peer-to-peer mesh, and the choice interacts heavily with OT versus CRDT.

In practice the overwhelming majority of production systems, including Google Docs, choose a central server even when the underlying data type could go peer-to-peer. A central server is not only the natural home for OT's total ordering — it is also where you do all the boring-but-essential work: authenticating users, enforcing who is allowed to edit, persisting the document durably, and serving the current state to a client that just opened the doc. Pure peer-to-peer is elegant on paper but pushes authentication, persistence, and discovery onto the clients, which is rarely worth it for a document-editing product. The common pattern is therefore "CRDT or OT for correctness, central server for everything operational."

8. Sync Architecture

The concrete architecture is clients talking to a sequencing server over a persistent connection (typically a WebSocket), with the server assigning a monotonically increasing sequence number to every operation and rebroadcasting it to all connected clients. A document store behind the server holds the durable op log and periodic snapshots so that a client opening the document can be brought up to the current state quickly.

Reading the flow:

• Clients. Each applies its own edits locally and immediately, then sends them to the server as operations. It also receives the server's ordered stream and reconciles it against any of its own operations still in flight.
• Sequencing server. The heart of the design. It receives operations, assigns each a global sequence number (the total order), appends them to the durable log, and rebroadcasts them. For OT it also runs the transform; for a CRDT it can simply relay, since the ids already define the order.
• Document store. Persists the operation log so nothing is lost if the server restarts, and stores periodic snapshots so a client does not have to replay millions of operations to open a long-lived document.

# server: transform (OT), assign a global order, persist, then fan out
function on_operation(client, op):     # op.base_seq = last server seq the client had seen
  for other in store.ops_since(op.base_seq):
    op = transform(op, other)          # OT: rebase over ops the client missed
  op.seq = next_sequence_number()      # the total order
  store.append(op)                     # durable before broadcast
  client.send(ACK(op.seq))             # sender learns its op's final seq
  for peer in connected_clients:
    if peer != client:
      peer.send(op)                    # everyone applies same order
# CRDT: skip the transform loop; ids already define the order

The ack matters. Without it the sender cannot tell when its op is safely in the log, so it cannot move on to send its next op or know which server sequence number its own edit became. Systems in the Jupiter/Google Docs style keep at most one op (or one batch) in flight per client and send the next only after the ack arrives.

9. Cursors and Presence

A collaborative editor is not only about text — half of what makes it feel alive is seeing where other people are. Each client broadcasts its cursor position and current text selection, usually tagged with the user's name and color, so everyone can render the little labeled carets you see floating in the document.

Crucially, presence data is treated very differently from document operations. Cursor positions are ephemeral: they do not need to be persisted, they do not need exactly-once delivery, and a dropped update just means a cursor lags for a moment. So presence typically rides a separate, best-effort channel rather than the durable op log. When a remote edit shifts text around, each client also has to remap the cursor positions it is displaying, the same way operations are transformed, so that a collaborator's caret stays attached to the right place after an insert or delete upstream of it.

10. Offline Edits and Reconnection

Reconnect from a durable document version and pending operation IDs. In OT, transform each remote operation against pending local operations and the pending operations against the same pre-transform remote state, following the selected algorithm's control protocol. Sending several rebased pending operations all with one unchanged base sequence is not a complete submission protocol; acknowledge/rebase incrementally or submit a protocol-defined ordered batch.

CRDT reconciliation exchanges compatible state/operations and required causal context; 'any order' is valid only under the implementation's stated delivery/dependency rules. If server history/tombstones were compacted beyond the client's base, require snapshot/resync rather than silently dropping unsent edits. Bind document permissions, version, site incarnation, and dedup identity to every batch. Presence is ephemeral and is not part of the persisted editing history.

11. Tradeoffs

The OT-versus-CRDT decision is the one an interviewer most wants you to reason about out loud. Neither is strictly better; they trade complexity in different places.

The short version for an interview: choose OT when you already have a reliable central server and want a compact on-the-wire format, accepting the burden of getting the transform rules right. Choose a CRDT when you want decentralization, strong offline support, or simpler reasoning about convergence, and you can afford the metadata. Many modern systems even blend the two — using a central server for ordering and persistence while leaning on CRDT-style ids to make merges trivial.

12. Failure Modes

Worked example: two insertions at the same position

Both replicas start with AB. Alice inserts X at index 1; Bob inserts Y at index 1; alice sorts before bob.

Run a small, testable model

Download concepts.py. It uses only the Python 3.10+ standard library. From the directory where you saved it, run:

python3 concepts.py collaboration
python3 concepts.py test

The model tests a deterministic insert-only OT diamond and a simple two-phase set's deletion merge. Neither is a production text editor.

The program contains deterministic assertions and failure traces. It is a learning model, not a production service: it does not implement network consensus, distributed durability, authentication, or third-party delivery. Read its contracts and try changing an input before extending it.

13. A 45-Minute Interview Walkthrough

14. Common Mistakes

15. Summary

Collaborative editing is a replicated data structure that must converge no matter how edits interleave. The design is a few reinforcing decisions:

16. Check Yourself

1. Alice inserts "x" at position 5 while Bob concurrently deletes position 2. What does Bob apply when Alice's op reaches him?
   Answer

   Insert "x" at position 4, because Bob's delete removed one character before position 5.

2. Two users insert into the same gap at the same moment, and both pick the id 1.5. What goes wrong, and how do real CRDTs avoid it?
   Answer

   The two characters have equal ids, so replicas may order them differently and diverge. Real CRDTs add the site id and a counter to every id, so ids are always unique and ties break the same way everywhere.

3. Why does the server send an ack back to the sender instead of just broadcasting to the others?
   Answer

   The sender needs to know its op is durable and which sequence number it received, so it can update its base_seq and send the next op.

4. A client reconnects with 3 unsent local ops and the server has 10 new ops. Why can't the client just apply the 10 ops as they are?
   Answer

   Its local copy already includes the 3 local ops, so the remote positions are off. Each remote op must be transformed past the pending ops, and the pending ops past it, before applying and sending.

5. The op log grows about 2.6 TB a day. What do you do about it?
   Answer

   Take periodic snapshots, keep only recent ops hot, and move or compact older history. Opening a doc then loads a snapshot plus a short tail of ops.

6. Why is presence sent on a separate channel from document ops?
   Answer

   Cursor updates are frequent and ephemeral. Losing one is fine, so they do not belong in the durable, ordered op log.

17. Key Terms

Operation

A small change such as insert or delete at a position.

Operational Transformation (OT)

Rewriting an op so it applies correctly after a concurrent op.

CRDT

Data types with merge rules designed to converge after replicas have received compatible updates. State-based CRDT merges are associative, commutative, and idempotent; operation-based designs impose their own delivery/causality rules. Example and limits above.

Convergence

All replicas end with the same state after seeing the same ops.

Tombstone

A marker left for a deleted character so ids stay valid.

Sequence number

A sequence number records committed order within a stream. A cursor is a consumer's durable position in that stream, so it can resume without skipping missing events. An opaque identity is not automatically such a position. Example and limits above.

Snapshot and compaction

Saving full state so old ops can be dropped or archived.

Presence

Ephemeral info about who is here and where their cursor is.

18. Further Reading

• C. A. Ellis and S. J. Gibbs, "Concurrency Control in Groupware Systems," SIGMOD 1989, the original OT paper.
• D. Nichols, P. Curtis, M. Dixon and J. Lamping, "High-Latency, Low-Bandwidth Windowing in the Jupiter Collaboration System," UIST 1995, the client-server OT model behind Google Docs.
• M. Shapiro, N. Preguiça, C. Baquero and M. Zawirski, "Conflict-Free Replicated Data Types," SSS 2011.
• M. Kleppmann, V. Gomes, D. Mulligan and A. Beresford, "Interleaving Anomalies in Collaborative Text Editors," PaPoC 2019.
• Yjs documentation (docs.yjs.dev) and the Automerge documentation (automerge.org).