Design a Collaborative Document Editor (Google Docs / Notion)

Per-user operation rate (actively typing):
  Character inserts:    3-5 ops/sec (typing speed ~60 WPM)
  Deletes/backspace:    0.5-1 ops/sec
  Formatting:           0.1 ops/sec (bold, italic, heading changes)
  Cursor/selection:     2-3 ops/sec (mouse clicks, arrow keys)
  ─────────────────────────────────
  Total per active user: ~8 ops/sec

Per-document (20 concurrent editors, 5 actively typing):
  Active typing ops:    5 users × 8 ops/sec = 40 ops/sec
  Presence updates:     20 users × 0.5/sec = 10 ops/sec (cursor position)
  ─────────────────────────────────
  Total per document:   ~50 ops/sec

Platform scale (Google Docs level):
  Active documents:     10M documents with ≥1 user connected
  Collaborative docs:   1M documents with ≥2 users (10%)
  Peak concurrent:      50M WebSocket connections
  Total operations:     1M docs × 50 ops/sec = 50M ops/sec platform-wide

Per-document fan-out (20 collaborators):
  Operations generated: 50 ops/sec
  Fan-out per op:       19 messages (to all other users)
  Total messages:       50 × 19 = 950 messages/sec per document

Platform-wide fan-out:
  1M collaborative docs × 950 msgs/sec = 950M messages/sec
  
  But most docs have 2-3 collaborators, not 20:
  Realistic average:    1M docs × 2.5 collaborators × 8 ops/sec × 1.5 fan-out
                      = 30M messages/sec (more realistic)

Message size:
  Typical operation:    ~100-200 bytes (type, position, content, metadata)
  Presence update:      ~50 bytes (cursor position, user ID)
  
Bandwidth:
  30M msgs/sec × 150 bytes = 4.5 GB/sec outbound
  Per WebSocket server (10K connections): ~900 KB/sec outbound (trivial)

Document storage:
  Average document size:  50 KB (text content, ~10 pages)
  10M active documents:   500 GB (current state only)

Operation log (for version history):
  Per document: 50 ops/sec × 3600 sec/hour × 8 hours/day = 1.44M ops/day
  Per operation: 150 bytes
  Daily log per doc:      216 MB (for an actively edited doc)
  
  But most docs are edited for minutes, not hours:
  Realistic: avg 500 ops/day per active doc × 150 bytes = 75 KB/day
  10M docs × 75 KB/day = 750 GB/day of operation logs
  → 274 TB/year (without compaction)

Snapshot compaction:
  Store full snapshot every 1000 operations
  Discard individual ops older than snapshot
  Reduces storage by ~90%: 274 TB → ~27 TB/year

Implication:
  → Operation log grows fast. Snapshot compaction is mandatory.
  → Hot documents (actively edited) keep ops in memory/Redis.
  → Cold documents (not edited in 24h) only store snapshots in blob storage.

Platform connections:
  50M concurrent WebSocket connections (Google Docs scale)
  
Per server capacity:
  Single server: ~50K-100K WebSocket connections (with epoll/kqueue)
  Memory per connection: ~10 KB (buffers, state, user metadata)
  Memory per server: 100K × 10 KB = 1 GB (connection state only)
  
Servers needed:
  50M / 100K = 500 WebSocket servers minimum
  With 2× headroom: 1000 servers

Connection routing:
  All users editing the same document MUST connect to the same server
  (or the same server group with shared state)
  → Consistent hashing by document_id to route connections
  → If a server dies, all its documents' connections must reconnect
     to the new owner (graceful handoff)

// Create a new document
POST /api/v1/documents
Body: { title: "Q3 Planning", workspace_id: "ws_123" }
Response: { document_id: "doc_456", title: "Q3 Planning", created_at: ISO8601 }

// Load document (initial state for editor)
GET /api/v1/documents/:documentId
Response: {
  document_id: "doc_456",
  title: "Q3 Planning",
  content: { /* document tree / CRDT state */ },
  version: 4827,           // current server version (for sync)
  collaborators: [         // who's currently connected
    { user_id: "u_1", name: "Alice", cursor: { block: 3, offset: 12 } }
  ],
  permissions: { role: "editor" }  // viewer | commenter | editor | owner
}

// Get version history
GET /api/v1/documents/:documentId/versions?limit=50
Response: {
  versions: [
    { version: 4827, author: "Alice", timestamp: ISO8601, summary: "Edited section 3" },
    { version: 4800, author: "Bob", timestamp: ISO8601, summary: "Added table" },
  ]
}

// Restore to a previous version
POST /api/v1/documents/:documentId/restore
Body: { target_version: 4800 }
Response: { version: 4828, restored_from: 4800 }

// Connection handshake
// Client connects: wss://collab.example.com/ws?doc=doc_456&token=jwt_...
// Server responds with current state:
{
  type: "init",
  version: 4827,                    // server's current version
  pending_ops: [],                  // ops the server has but client hasn't seen
  collaborators: [...]              // current presence list
}

// Client submits an operation
// Client → Server
{
  type: "op",
  client_id: "c_abc",
  client_version: 4825,            // last server version client has seen
  operation: {
    type: "insert",
    path: [3, "children", 0, "text"],  // position in document tree
    offset: 12,                     // character offset within text node
    content: "Hello",               // inserted text
  },
  local_seq: 42                     // client's local sequence number
}

// Server acknowledges (operation accepted and assigned a version)
// Server → Client (sender only)
{
  type: "ack",
  local_seq: 42,                   // which client op was acknowledged
  server_version: 4828             // assigned server version
}

// Server broadcasts to other clients
// Server → Client (all others in document)
{
  type: "remote_op",
  server_version: 4828,
  author: { user_id: "u_1", name: "Alice" },
  operation: {
    type: "insert",
    path: [3, "children", 0, "text"],
    offset: 12,
    content: "Hello",
  }
}

// Presence updates (cursor, selection)
// Client → Server (throttled to 2-3/sec)
{
  type: "presence",
  cursor: { path: [3, "children", 0, "text"], offset: 17 },
  selection: null  // or { anchor: {...}, focus: {...} }
}

// Server → All other clients
{
  type: "presence_update",
  user: { user_id: "u_1", name: "Alice", color: "#4A90D9" },
  cursor: { path: [3, "children", 0, "text"], offset: 17 },
  selection: null
}

// Text operations (within a text node)
type TextOp = 
  | { type: "insert"; path: Path; offset: number; content: string }
  | { type: "delete"; path: Path; offset: number; length: number }

// Structural operations (document tree)
type StructuralOp =
  | { type: "insert_node"; path: Path; node: DocumentNode }
  | { type: "remove_node"; path: Path }
  | { type: "move_node"; from: Path; to: Path }

// Formatting operations (marks/attributes)
type FormatOp =
  | { type: "add_mark"; path: Path; offset: number; length: number; mark: Mark }
  | { type: "remove_mark"; path: Path; offset: number; length: number; mark: Mark }
  | { type: "set_property"; path: Path; key: string; value: unknown }

// Composite operation (atomic batch)
type CompositeOp = {
  type: "composite";
  operations: (TextOp | StructuralOp | FormatOp)[];
  // All ops in a composite are applied atomically
  // Used for: paste, find-replace, undo
}

// Path: array of indices navigating the document tree
// Example: [3, "children", 0, "text"] = 4th block → children → 1st child → text content
type Path = (number | string)[];

// A document is a tree of nodes
// Example: "Hello **world**" in a heading
{
  type: "document",
  children: [
    {
      type: "heading",
      properties: { level: 2 },
      children: [
        { type: "text", content: "Hello " },
        { type: "text", content: "world", marks: ["bold"] }
      ]
    },
    {
      type: "paragraph",
      children: [
        { type: "text", content: "This is a paragraph with " },
        { type: "text", content: "italic text", marks: ["italic"] },
        { type: "text", content: "." }
      ]
    },
    {
      type: "table",
      children: [
        {
          type: "table_row",
          children: [
            { type: "table_cell", children: [{ type: "text", content: "A1" }] },
            { type: "table_cell", children: [{ type: "text", content: "B1" }] }
          ]
        }
      ]
    }
  ]
}

-- Documents: metadata and access control
CREATE TABLE documents (
  id            UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  title         TEXT NOT NULL DEFAULT 'Untitled',
  workspace_id  UUID REFERENCES workspaces(id),
  owner_id      UUID REFERENCES users(id),
  current_version INT NOT NULL DEFAULT 0,
  content_snapshot JSONB,          -- latest full document tree (for fast load)
  snapshot_version INT NOT NULL DEFAULT 0,  -- version of the snapshot
  is_archived   BOOLEAN DEFAULT false,
  created_at    TIMESTAMPTZ,
  updated_at    TIMESTAMPTZ,
  delete_info   JSONB
);

-- Operation log: every edit ever made (append-only)
CREATE TABLE document_operations (
  id            BIGSERIAL PRIMARY KEY,
  document_id   UUID REFERENCES documents(id),
  version       INT NOT NULL,              -- server-assigned sequential version
  author_id     UUID REFERENCES users(id),
  operation     JSONB NOT NULL,            -- the operation payload
  created_at    TIMESTAMPTZ DEFAULT NOW(),
  UNIQUE(document_id, version)
);
CREATE INDEX idx_doc_ops_version ON document_operations(document_id, version);

-- Snapshots: periodic full-state captures (for fast loading + log compaction)
CREATE TABLE document_snapshots (
  id            UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  document_id   UUID REFERENCES documents(id),
  version       INT NOT NULL,
  content       JSONB NOT NULL,            -- full document tree at this version
  created_at    TIMESTAMPTZ DEFAULT NOW(),
  delete_info   JSONB
);
CREATE INDEX idx_snapshots_doc_version ON document_snapshots(document_id, version);

-- Comments: anchored to document positions
CREATE TABLE document_comments (
  id            UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  document_id   UUID REFERENCES documents(id),
  author_id     UUID REFERENCES users(id),
  anchor_path   JSONB NOT NULL,            -- path + offset range in document tree
  anchor_version INT NOT NULL,             -- version when comment was created
  content       TEXT NOT NULL,
  is_resolved   BOOLEAN DEFAULT false,
  parent_id     UUID REFERENCES document_comments(id),  -- for threads
  created_at    TIMESTAMPTZ,
  updated_at    TIMESTAMPTZ,
  delete_info   JSONB
);

-- Document permissions
CREATE TABLE document_permissions (
  id            UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  document_id   UUID REFERENCES documents(id),
  user_id       UUID REFERENCES users(id),
  role          TEXT NOT NULL DEFAULT 'viewer',  -- viewer | commenter | editor | owner
  created_at    TIMESTAMPTZ,
  updated_at    TIMESTAMPTZ,
  delete_info   JSONB,
  UNIQUE(document_id, user_id)
);

// Held in memory on the collaboration server while document is active
interface DocumentSession {
  documentId: string;
  
  // Current document state
  currentVersion: number;
  documentTree: DocumentNode;        // full tree in memory for fast access
  
  // Operation buffer (recent ops for transformation)
  recentOps: Operation[];            // last N ops (for transforming incoming ops)
  lastSnapshotVersion: number;       // version of last persisted snapshot
  
  // Connected clients
  clients: Map<string, ClientState>; // clientId → state
  
  // Persistence queue
  pendingPersist: Operation[];       // ops not yet written to DB
  persistTimer: NodeJS.Timeout;      // flush every 500ms or 50 ops
}

interface ClientState {
  userId: string;
  clientId: string;
  websocket: WebSocket;
  lastAckedVersion: number;          // last version client confirmed receiving
  cursor: CursorPosition | null;
  selection: SelectionRange | null;
  color: string;                     // assigned collaboration color
}

// Memory per active document:
// Document tree: ~50 KB (average)
// Recent ops buffer (1000 ops): ~150 KB
// Client state (20 clients): ~10 KB
// Total: ~210 KB per active document
// 100K active documents: ~21 GB (fits in a single large server)

// All clients for document X must connect to the same collaboration server
// Use consistent hashing to map document_id → server instance

class DocumentRouter {
  private ring: ConsistentHashRing;
  
  getServerForDocument(documentId: string): ServerInstance {
    // Hash the document ID to find the owning server
    return this.ring.getNode(documentId);
  }
  
  // When a server dies, its documents are redistributed to neighbors
  handleServerFailure(failedServer: ServerInstance) {
    const affectedDocs = this.ring.getDocumentsOnNode(failedServer);
    this.ring.removeNode(failedServer);
    
    // Each affected document's clients will reconnect
    // New owner server loads document from latest snapshot + op log
    for (const docId of affectedDocs) {
      const newOwner = this.ring.getNode(docId);
      newOwner.loadDocument(docId); // Load from persistence layer
    }
  }
}

// Client connection flow:
// 1. Client calls REST API: GET /api/v1/documents/:id/connect
// 2. API returns WebSocket URL: wss://collab-server-7.example.com/ws?doc=doc_456
// 3. Client connects to the specific server that owns this document
// 4. If server is unavailable, client retries with exponential backoff
//    Gateway re-routes to new owner after failover

User types "H" at position 12 in paragraph 3:

Client side (0ms):
  1. Apply locally → user sees "H" instantly
  2. Create operation: { type: "insert", path: [3, "text"], offset: 12, content: "H" }
  3. Attach client_version: 4825 (last server version seen)
  4. Add to pending queue, send over WebSocket

Network (20-50ms):
  5. WebSocket frame arrives at collaboration server

Server side (0.1-1ms):
  6. Receive op with client_version=4825
  7. Server is at version 4828 → 3 ops happened since client last synced
  8. Transform incoming op against ops 4826, 4827, 4828
     (adjust position if earlier inserts shifted text)
  9. Apply transformed op to server document tree
  10. Assign version 4829
  11. Append to operation log (in-memory buffer, async persist)
  12. Send ACK to sender: { type: "ack", server_version: 4829 }
  13. Broadcast to all other clients: { type: "remote_op", version: 4829, op: ... }

Other clients (20-50ms network):
  14. Receive remote_op
  15. Transform against any pending local ops (not yet ACKed)
  16. Apply to local document tree
  17. Re-render affected paragraph

Total end-to-end: 50-150ms (dominated by network RTT)

Initial document: "ABCD"

Alice's operation: insert("X", position=1)  → "AXBCD"
Bob's operation:   delete(position=2)        → "ABD"

Without conflict resolution:
  If we apply Alice then Bob: "AXBCD" → delete pos 2 → "AXCD" (Bob deleted 'B')
  If we apply Bob then Alice: "ABD" → insert 'X' at pos 1 → "AXBD"
  
  Different results! "AXCD" ≠ "AXBD"
  
  The correct result should be: "AXBD"
  (Alice's X is inserted, Bob's deletion of C is preserved)
  
  Why? Bob intended to delete the character 'C' (the 3rd character).
  After Alice's insert, 'C' moved from position 2 to position 3.
  So Bob's delete should target position 3, not position 2.

Choose OT if:
  ✓ You need a proven, battle-tested approach (Google Docs model)
  ✓ Memory efficiency is critical (millions of documents)
  ✓ You already have a central server (which you do for persistence)
  ✓ Offline editing is not a primary requirement

Choose CRDT if:
  ✓ Offline-first is a core requirement (mobile apps, unreliable networks)
  ✓ You want peer-to-peer collaboration (no server dependency)
  ✓ You're building on modern libraries (Yjs, Automerge)
  ✓ You can tolerate higher memory usage per document

For this design (Google Docs-style):
  → OT with server-authoritative ordering
  → Server is already required for persistence, permissions, presence
  → Memory efficiency matters at 10M documents
  → Offline is supported via operation buffering + rebase on reconnect

class CollaborationClient {
  private document: DocumentTree;
  private serverVersion: number;
  private pendingOps: Operation[] = [];    // sent but not ACKed
  private localBuffer: Operation[] = [];   // not yet sent
  
  // User types a character
  handleLocalEdit(op: Operation) {
    // 1. Apply immediately (user sees it instantly)
    this.document = applyOp(this.document, op);
    
    // 2. Buffer the operation
    this.localBuffer.push(op);
    
    // 3. If nothing is pending (waiting for ACK), send immediately
    if (this.pendingOps.length === 0) {
      this.flushBuffer();
    }
    // Otherwise, wait for ACK before sending next batch
  }
  
  // Server acknowledges our operation
  handleAck(ack: { local_seq: number; server_version: number }) {
    // Remove from pending
    this.pendingOps.shift();
    this.serverVersion = ack.server_version;
    
    // Send next buffered ops if any
    if (this.localBuffer.length > 0) {
      this.flushBuffer();
    }
  }
  
  // Receive a remote operation from another user
  handleRemoteOp(remoteOp: { operation: Operation; server_version: number }) {
    this.serverVersion = remoteOp.server_version;
    
    // Transform remote op against ALL our pending + buffered ops
    // (because our local state includes ops the server hasn't seen yet)
    let transformed = remoteOp.operation;
    
    for (const pendingOp of this.pendingOps) {
      const [transformedRemote, transformedLocal] = transformPair(transformed, pendingOp);
      transformed = transformedRemote;
      // Also update our pending op (it now accounts for the remote change)
    }
    
    for (const bufferedOp of this.localBuffer) {
      const [transformedRemote, transformedLocal] = transformPair(transformed, bufferedOp);
      transformed = transformedRemote;
    }
    
    // Apply the transformed remote op to our local document
    this.document = applyOp(this.document, transformed);
    // Re-render the affected region
  }
}

Connection States:
  CONNECTING → SYNCING → ACTIVE → DISCONNECTED → RECONNECTING → SYNCING → ...

CONNECTING:
  Client opens WebSocket to collaboration server
  Sends auth token + document_id + last_known_version
  
SYNCING:
  Server sends all operations since client's last_known_version
  Client applies them to catch up to current state
  If gap > 1000 ops: server sends full snapshot instead
  
ACTIVE:
  Bidirectional operation streaming
  Client sends local ops, receives remote ops + ACKs
  Heartbeat every 30 seconds (detect dead connections)
  
DISCONNECTED:
  Network failure detected (heartbeat timeout or WebSocket close)
  Client buffers all local operations in memory
  Shows "Reconnecting..." indicator to user
  User can continue editing (offline mode)
  
RECONNECTING:
  Exponential backoff: 1s, 2s, 4s, 8s, 16s, 30s (max)
  On reconnect: send last_known_version + all buffered ops
  Server transforms buffered ops against missed server ops
  Resume ACTIVE state

class OperationBatcher {
  private buffer: Operation[] = [];
  private flushTimer: NodeJS.Timeout | null = null;
  private readonly maxBatchSize = 20;
  private readonly maxDelay = 50; // ms — max time before flush
  
  add(op: Operation) {
    this.buffer.push(op);
    
    // Flush immediately if batch is full
    if (this.buffer.length >= this.maxBatchSize) {
      this.flush();
      return;
    }
    
    // Otherwise, set a timer to flush after maxDelay
    if (!this.flushTimer) {
      this.flushTimer = setTimeout(() => this.flush(), this.maxDelay);
    }
  }
  
  private flush() {
    if (this.buffer.length === 0) return;
    
    if (this.flushTimer) {
      clearTimeout(this.flushTimer);
      this.flushTimer = null;
    }
    
    // Compose multiple ops into a single composite operation
    const composite: CompositeOperation = {
      type: 'composite',
      operations: [...this.buffer]
    };
    
    this.transport.send(composite);
    this.buffer = [];
  }
}

// Behavior:
// Fast typing (10 chars/sec): batches of 1-2 ops every 50ms
// Paste (500 chars): single composite op, sent immediately
// Idle then type: first char sent after 50ms delay (imperceptible)
// Net effect: 60-80% reduction in WebSocket messages with <50ms added latency

interface UserPresence {
  userId: string;
  name: string;
  avatarUrl: string;
  color: string;              // assigned collaboration color (#4A90D9, #E74C3C, etc.)
  
  // Cursor position (where the caret is)
  cursor: {
    path: Path;               // path in document tree (e.g., [3, "children", 0, "text"])
    offset: number;           // character offset within the text node
  } | null;                   // null = user has no cursor in document (e.g., in comments panel)
  
  // Selection range (highlighted text)
  selection: {
    anchor: { path: Path; offset: number };  // where selection started
    focus: { path: Path; offset: number };   // where selection ended
  } | null;
  
  // Activity state
  lastActiveAt: number;       // timestamp of last edit/cursor move
  status: 'active' | 'idle' | 'away';  // idle after 60s, away after 5min
}

// Color assignment: deterministic based on user position in collaborator list
const COLLABORATION_COLORS = [
  '#4A90D9', '#E74C3C', '#27AE60', '#F39C12',
  '#9B59B6', '#1ABC9C', '#E67E22', '#2ECC71',
  '#3498DB', '#E91E63', '#00BCD4', '#FF5722',
];

function assignColor(userId: string, collaborators: string[]): string {
  const index = collaborators.indexOf(userId);
  return COLLABORATION_COLORS[index % COLLABORATION_COLORS.length];
}

// When a remote operation arrives, transform all other users' cursors
function transformCursor(cursor: CursorPosition, op: Operation): CursorPosition {
  if (!cursor) return cursor;
  
  // Only transform if the op affects the same text node
  if (!pathEquals(cursor.path, op.path)) return cursor;
  
  if (op.type === 'insert') {
    if (op.offset <= cursor.offset) {
      // Insert happened before cursor → push cursor right
      return { ...cursor, offset: cursor.offset + op.content.length };
    }
    return cursor; // Insert after cursor → no change
  }
  
  if (op.type === 'delete') {
    if (op.offset + op.length <= cursor.offset) {
      // Delete happened entirely before cursor → pull cursor left
      return { ...cursor, offset: cursor.offset - op.length };
    }
    if (op.offset < cursor.offset) {
      // Delete overlaps cursor position → cursor moves to delete start
      return { ...cursor, offset: op.offset };
    }
    return cursor; // Delete after cursor → no change
  }
  
  return cursor;
}

// Applied on every remote operation:
function handleRemoteOp(op: Operation) {
  // 1. Apply op to document (as before)
  // 2. Transform all remote cursors
  for (const [userId, presence] of this.collaborators) {
    if (userId === op.authorId) continue; // author's cursor is in their own update
    presence.cursor = transformCursor(presence.cursor, op);
    if (presence.selection) {
      presence.selection.anchor = transformCursor(presence.selection.anchor, op);
      presence.selection.focus = transformCursor(presence.selection.focus, op);
    }
  }
  // 3. Re-render cursors at new positions
}

class PresenceManager {
  private lastBroadcast = 0;
  private pendingUpdate: UserPresence | null = null;
  private throttleMs = 300; // max 3 updates/sec
  
  updateCursor(cursor: CursorPosition) {
    this.pendingUpdate = { ...this.currentPresence, cursor };
    
    const now = Date.now();
    const elapsed = now - this.lastBroadcast;
    
    if (elapsed >= this.throttleMs) {
      // Enough time passed — send immediately
      this.broadcast();
    } else {
      // Too soon — schedule for later (debounce)
      if (!this.timer) {
        this.timer = setTimeout(() => this.broadcast(), this.throttleMs - elapsed);
      }
    }
  }
  
  private broadcast() {
    if (!this.pendingUpdate) return;
    
    this.websocket.send(JSON.stringify({
      type: 'presence',
      cursor: this.pendingUpdate.cursor,
      selection: this.pendingUpdate.selection,
    }));
    
    this.lastBroadcast = Date.now();
    this.pendingUpdate = null;
    this.timer = null;
  }
}

// Server-side: presence updates are NOT persisted
// They're broadcast to other clients and forgotten
// If a client reconnects, it gets current presence from the session state
// No operation log, no transformation, no versioning — just latest-wins

// Client-side activity detection
class ActivityTracker {
  private lastActivity = Date.now();
  private currentStatus: 'active' | 'idle' | 'away' = 'active';
  
  onUserActivity() {
    this.lastActivity = Date.now();
    if (this.currentStatus !== 'active') {
      this.currentStatus = 'active';
      this.broadcastStatusChange('active');
    }
  }
  
  // Check every 10 seconds
  checkStatus() {
    const idle = Date.now() - this.lastActivity;
    
    if (idle > 300000 && this.currentStatus !== 'away') {    // 5 min
      this.currentStatus = 'away';
      this.broadcastStatusChange('away');
    } else if (idle > 60000 && this.currentStatus === 'active') {  // 1 min
      this.currentStatus = 'idle';
      this.broadcastStatusChange('idle');
    }
  }
}

// Visual representation:
// Active: solid colored cursor + name label
// Idle:   faded cursor + "(idle)" suffix
// Away:   cursor hidden, name in collaborator list grayed out

ONLINE (normal):
  User types → apply locally → send to server → receive ACK → done

OFFLINE (disconnected):
  User types → apply locally → store in IndexedDB → queue for later
  User types → apply locally → store in IndexedDB → queue for later
  ... (can accumulate hundreds of operations)

RECONNECTION:
  1. Connect WebSocket, send last_known_version (e.g., 4825)
  2. Server responds with all ops since 4825 (e.g., versions 4826-4900 = 75 ops)
  3. Client receives 75 remote ops it missed
  4. Client transforms its buffered ops against the 75 remote ops
  5. Client transforms the 75 remote ops against its buffered ops
  6. Client applies transformed remote ops to local document
  7. Client sends transformed buffered ops to server
  8. Server ACKs each one, assigns versions 4901, 4902, ...
  9. Sync complete — client and server are consistent

// Write to IndexedDB BEFORE applying locally
async function handleLocalEdit(op: Operation) {
  // 1. Persist to IndexedDB first (crash-safe)
  await this.db.put('pending_ops', {
    id: this.localSeq++,
    documentId: this.documentId,
    operation: op,
    timestamp: Date.now(),
    serverVersion: this.lastKnownVersion
  });
  
  // 2. Apply to local document (now safe — recoverable from IDB)
  this.document = applyOp(this.document, op);
  
  // 3. Queue for server submission
  this.localBuffer.push(op);
}

// On app startup: check for unsubmitted operations
async function recoverFromCrash() {
  const pendingOps = await this.db.getAll('pending_ops');
  
  if (pendingOps.length > 0) {
    // Rebuild local document from last snapshot + pending ops
    const snapshot = await this.db.get('document_snapshot', this.documentId);
    this.document = snapshot.content;
    
    for (const pending of pendingOps) {
      this.document = applyOp(this.document, pending.operation);
      this.localBuffer.push(pending.operation);
    }
    
    // Reconnect and submit buffered ops
    await this.connect();
  }
}

class SnapshotManager {
  private readonly SNAPSHOT_INTERVAL = 1000;  // every 1000 ops
  private readonly TIME_INTERVAL = 3600000;   // or every hour (whichever comes first)
  private lastSnapshotVersion: number;
  private lastSnapshotTime: number;
  
  shouldCreateSnapshot(currentVersion: number): boolean {
    const opsSinceSnapshot = currentVersion - this.lastSnapshotVersion;
    const timeSinceSnapshot = Date.now() - this.lastSnapshotTime;
    
    return opsSinceSnapshot >= this.SNAPSHOT_INTERVAL 
        || timeSinceSnapshot >= this.TIME_INTERVAL;
  }
  
  async createSnapshot(documentId: string, document: DocumentTree, version: number) {
    // Persist full document state
    await db.insert('document_snapshots', {
      document_id: documentId,
      version: version,
      content: document,  // full JSON tree
      created_at: new Date()
    });
    
    // Update document's current snapshot reference
    await db.update('documents', documentId, {
      content_snapshot: document,
      snapshot_version: version
    });
    
    this.lastSnapshotVersion = version;
    this.lastSnapshotTime = Date.now();
  }
}

// Document loading flow:
// 1. Fetch latest snapshot (version 4000, full document tree)
// 2. Fetch operations 4001-4827 (827 ops to replay)
// 3. Apply 827 ops to snapshot → current document state
// Without snapshots: replay ALL ops from version 0 (could be millions)