Collaborative Real-Time Editing

The Problem

Google Docs, Figma, and Notion allow multiple users to edit the same document simultaneously without conflicts. This requires solving one of the hardest problems in distributed systems: concurrent edits on shared state. When Alice inserts “hello” at position 5 while Bob deletes character 3, both operations must be applied on both clients to produce the same final document — regardless of the order they arrive. The system must handle network latency, offline edits, cursor/selection tracking, and undo/redo, all while feeling instantaneous to each user.

Architectural Approaches

Architecture

Loading diagram...

Key Components

Data Model

Loading diagram...

How CRDTs Work for Text

Text CRDTs assign each character a unique, globally ordered ID that determines its position in the document, independent of array indexes.

Yjs approach (YATA algorithm):

• Each character has an ID: (clientID, clock) — e.g., (Alice, 5)
• Each character knows its left neighbor’s ID
• When inserting between two characters, the new character’s position is determined by its left neighbor, making concurrent inserts at the same position deterministic
• Deletes mark characters as tombstones (logically deleted but still in the structure)

Example of concurrent edits:

• Document: “AC”
• Alice inserts “B” between A and C → “ABC”
• Bob inserts “X” between A and C → “AXC” (concurrently)
• When both operations are merged, the CRDT determines a consistent ordering: “ABXC” or “AXBC” — the same on both clients, determined by the character IDs

Why it always converges: The unique IDs and ordering rules are commutative — applying Alice’s edit then Bob’s produces the same result as applying Bob’s then Alice’s. This is the mathematical guarantee of CRDTs.

Libraries:

• Yjs: Most popular, small bundle (15KB), supports ProseMirror, CodeMirror, Monaco, Tiptap
• Automerge: Research-quality, supports JSON documents, Rust core with WASM bindings
• Diamond Types: Rust-based, extremely memory-efficient, designed for performance

Awareness and Cursor Synchronization

Seeing other users’ cursors and selections is essential for the collaborative experience.

Awareness protocol (Yjs):

• Each client broadcasts its “awareness state”: cursor position, selection range, user name, user color
• Updates sent via WebSocket alongside document operations
• Awareness states have a 30-second timeout — if not refreshed, the user is considered disconnected

Cursor position challenges:

• Cursor positions are indexes into the document. When another user inserts text before your cursor, your cursor position must shift.
• For OT: transform cursor positions using the same transform functions as text operations
• For CRDTs: store cursor position as a reference to a character ID (not an index). The cursor “follows” the character regardless of insertions/deletions around it.

Visual design:

• Each user gets a distinct color (from a predefined palette)
• Show a thin vertical line (caret) at their cursor position
• Show a colored highlight for their selection range
• Display the user’s name in a small label above the cursor
• Fade out cursors of idle users (no activity for 60 seconds)

Performance: Don’t send cursor updates on every keystroke. Throttle to 50-100ms intervals. Use a separate “awareness” channel that’s lower priority than document operations.

Offline Editing and Conflict Resolution

True offline support is a key advantage of CRDTs over OT.

Offline workflow:

1. User edits the document while disconnected. All operations are applied to the local CRDT replica.
2. On reconnection, the client sends its accumulated operations to the server.
3. The server merges the operations with any changes made by other users during the disconnection.
4. The server sends back any operations the offline client missed.
5. Both sides converge to the same state — guaranteed by the CRDT.

No conflicts: Unlike traditional merge (Git-style with conflict markers), CRDTs never produce conflicts. Concurrent edits to the same paragraph always merge deterministically. The result may not be what either user intended (if they edited the same sentence), but it’s always a valid document state.

Long offline periods: If a user is offline for days, the merge may produce unexpected results. Consider showing a “merge preview” UI that highlights what changed while they were away, similar to a diff view.

OT limitations: Traditional OT requires a central server to order operations. Offline OT is possible (Google Docs buffers operations and sends on reconnect) but requires the server to be available to reconcile. Extended offline editing with OT is fragile.

Storage: Offline clients must store their local CRDT state and pending operations in IndexedDB or SQLite. On reconnection, sync the pending operations first, then verify convergence by comparing document checksums.

Real-World Examples

Architectural Tradeoffs

# Learn the System Design of: Collaborative Real-Time Editing

You are an expert software architect and teacher. I want to understand collaborative real-time editing as a practical system design capability. (CRDTs vs Operational Transform for conflict-free concurrent document editing).

Use the following architectural guide as a learning reference. Avoid one-size-fits-all recommendations. Keep assumptions, costs, and tradeoffs explicit.

---

import { Mermaid, ComponentList, ComponentCard, ApproachList, Approach, Example, Tradeoff } from '@/components/mdx';

## The Problem

Google Docs, Figma, and Notion allow multiple users to edit the same document simultaneously without conflicts. This requires solving one of the hardest problems in distributed systems: concurrent edits on shared state. When Alice inserts "hello" at position 5 while Bob deletes character 3, both operations must be applied on both clients to produce the same final document — regardless of the order they arrive. The system must handle network latency, offline edits, cursor/selection tracking, and undo/redo, all while feeling instantaneous to each user.

## Architectural Approaches

<ApproachList>
<Approach
  name="Operational Transform (OT)"
  pros={[
    'Well-understood — decades of research and production use',
    'Compact operations — efficient over the network',
    'Central server simplifies conflict resolution',
    'Good support for rich text (formatting, embeds)',
  ]}
  cons={[
    'Transform functions are notoriously hard to get right',
    'Requires a central server for operation ordering',
    "Doesn't work well offline or in peer-to-peer scenarios",
    'Complexity explodes with rich document types (tables, nested structures)',
  ]}
>
Each edit is represented as an **operation** (insert, delete, retain). When concurrent operations arrive, a **transform function** adjusts their positions so they can be applied in any order and produce the same result. The server acts as a central auth...

[Full prompt copied to clipboard]