Design Case Studies · Lesson 19

Design: Collaborative Editing API

Collaborative applications like Google Docs and Figma allow multiple users to edit the same document concurrently. Under the hood, this requires resolving conflicts deterministically across geo-distributed clients. We must design a robust API and synchronization model using Operational Transformation (OT) or Conflict-Free Replicated Data Types (CRDTs) to prevent data loss and document divergence.

Requirements

Designing a collaborative editing system requires addressing distinct networking and data-integrity constraints:

• Consistency. All clients editing a document must converge to the exact same state once all edits are processed. Divergence (where users see different versions) is unacceptable.
• Low Latency. Local edits must render immediately on the editor's screen (sub-10ms UI response) and propagate to other users in under 100ms.
• Offline Support. A user must be able to continue editing during brief network disconnects and merge changes cleanly upon reconnecting.
• Scale. The API must handle document sessions with dozens of active simultaneous typers and thousands of concurrent read-only viewers.

Design decisions

Transport Protocol: WebSockets vs. SSE vs. HTTP/2

Since editing requires bidirectional, low-latency, real-time message streams, WebSockets are the standard transport choice. Clients establish a persistent connection to a session gateway server. WebSockets avoid HTTP header overhead on high-frequency keystroke messages. For read-only viewers, Server-Sent Events (SSE) or HTTP/2 streams are highly efficient alternatives to conserve gateway socket memory.

Operational Transformation (OT) vs. CRDTs

The choice of conflict resolution model determines your API structure and backend storage requirements:

Synchronization & Versioning Loops

To keep edit sizes small, we use **Delta Synchronization**. Clients track their local revision index (e.g., rev=42). When sending an edit, they attach their base revision. The server checks the global sequence. If another edit was accepted first (e.g., global sequence is now 43), the server transforms the incoming edit to account for the changes in version 43, commits the transformed edit as version 44, and broadcasts it to all other clients.

The API model

Establishing editing session

Before initiating the WebSocket loop, the client makes a REST request to obtain the current snapshot of the document and locate the target session server.

# Request document snapshot and session token
GET /v1/documents/doc_abc123/session HTTP/1.1
Authorization: Bearer user-token-xyz

# Response returns version metadata and gateway WebSocket URL
HTTP/1.1 200 OK
Content-Type: application/json

{
  "document_id": "doc_abc123",
  "revision": 1482,
  "content": "Hello, world!",
  "websocket_url": "wss://coll-edge-eu.example.com/session/doc_abc123"
}

WebSocket Edit Event (OT Model)

When the client types, it sends an operations array over the WebSocket connection. The server validates the base revision, applies transformations if needed, assigns the next global revision, and broadcasts it.

// Client → Server: User inserts "!" at index 12 based on revision 1482
{
  "type": "apply_op",
  "base_revision": 1482,
  "ops": [
    { "type": "insert", "index": 12, "value": "!" }
  ]
}

// Server → Client (Broadcast): Broadcasts the accepted operation
{
  "type": "op_broadcast",
  "revision": 1483,
  "client_id": "client_alice",
  "ops": [
    { "type": "insert", "index": 12, "value": "!" }
  ]
}

Under the hood: OT synchronization loop

Operational Transformation utilizes a centralized server to serialize and transform incoming edits so that client states do not drift.

By the numbers: edit frequency & fan-out math

Let's evaluate the network capacity requirements for a real-time collaborative doc edit session.

Governing Equations

• Unbuffered Broadcast rate: If $N$ active writers are typing concurrently at keystroke rate $K$ (keystrokes/sec), and the server broadcasts every single edit to all $N$ writers: $$Msg_{rate} = N \times (N - 1) \times K$$ This scales quadratically: $O(N^2)$.
• Client-Side Buffering: If clients batch keystrokes and transmit edits at interval $T$ (seconds) rather than per-character: $$Msg_{rate} = N \times (N - 1) \times \frac{1}{T}$$
• Network Egress Bandwidth: The total egress data rate at the session server is: $$Bandwidth_{egress} = Msg_{rate} \times Payload_{size}$$

Scenario Parameters

• Active Typers ($N$): 20 concurrent users
• Keystroke Rate ($K$): 5 keystrokes per second
• Client Buffering Window ($T$): 200 ms (0.2s)
• Average JSON Payload size: 300 bytes

Worked Calculations: Impact of Client-Side Buffering

How to debug & inspect it

To inspect real-time collaborative edits, capture and view active WebSocket frames in Google Chrome DevTools (Network tab → WS) or use `wscat` to watch operational payload payloads.

Use the guide below to diagnose and resolve synchronization problems in real-time collaborative systems:

Sources & further reading

• Neil Fraser (Google) — Differential Synchronization — the core algorithm behind real-time collaborative text sync
• Yjs Paper — Real-time collaborative editing using CRDTs — deep technical details on Yjs metadata structures and performance optimization
• Figma Engineering — How Figma's Multiplayer Technology Works — case study of tree/graph-based CRDTs and session sync