System Design #9: Design a Collaborative Text Editor

// Two users type simultaneously:
// User A: insert "X" at position 5
// User B: insert "Y" at position 3

// Without transformation:
// A sees: "helloXworld" → insert Y at 3 → "helYloXworld" ✗
// B sees: "helYloworld" → insert X at 5 → "helYlXoworld" ✗
// Different results!

// With OT:
// Transform A's op against B's: A inserted after B's position, so shift A right
// A' = insert "X" at position 6 (5 + 1)
// Now both converge: "helYloXworld" ✓

interface Operation {
  type: 'insert' | 'delete' | 'retain';
  position: number;
  content?: string;  // For insert
  count?: number;    // For delete/retain
  userId: string;
  revision: number;  // Server revision at time of creation
}

// Each character has a unique, ordered ID
interface CRDTChar {
  id: { clock: number; clientId: string }; // Lamport timestamp
  value: string;
  parent: CRDTChar['id'] | null;           // Left neighbor at insertion time
  isDeleted: boolean;                        // Tombstone (never truly removed)
}

// Insertion: place between two existing characters
// The ID ordering guarantees deterministic merge
// Even if two users insert at the "same" position, 
// the client IDs break the tie deterministically

Client A                  Server (y-websocket)           Client B
┌─────────┐               ┌──────────────┐              ┌─────────┐
│ TipTap  │───updates───→ │  Broadcast   │ ←──updates──│ TipTap  │
│ Editor  │←──updates───  │  + Persist   │  ──updates→──│ Editor  │
│ + Yjs   │               │  (y-leveldb) │              │ + Yjs   │
│ binding │               └──────────────┘              │ binding │
└─────────┘                                             └─────────┘
     │                                                       │
     └── Local Yjs Doc (IndexedDB)                           └── Local Yjs Doc

interface CollaborativeDoc {
  id: string;
  title: string;
  
  // Yjs state
  ydoc: Y.Doc;              // The CRDT document
  content: Y.XmlFragment;   // Rich text content (maps to TipTap)
  
  // Awareness (ephemeral state — not persisted)
  awareness: {
    [clientId: string]: {
      user: { name: string; color: string; avatar: string };
      cursor: { anchor: number; head: number } | null;
      isTyping: boolean;
      lastActive: number;
    };
  };
  
  // Metadata (stored in regular DB, not CRDT)
  metadata: {
    created_at: string;
    updated_at: string;
    owner_id: string;
    collaborators: { user_id: string; permission: 'view' | 'edit' | 'comment' }[];
    word_count: number;
  };
}

// Version history entry
interface DocVersion {
  id: string;
  doc_id: string;
  snapshot: Uint8Array;    // Yjs encoded state vector
  created_at: string;
  created_by: string;
  title: string;           // Auto: "March 15, 2:30 PM" or user-named
}

import { Awareness } from 'y-protocols/awareness';

function setupAwareness(doc: Y.Doc, provider: WebsocketProvider) {
  const awareness = provider.awareness;
  
  // Set local user info
  awareness.setLocalState({
    user: {
      name: currentUser.name,
      color: getCollaboratorColor(currentUser.id),
      avatar: currentUser.avatar_url,
    },
    cursor: null,
  });
  
  // Update cursor position on selection change
  editor.on('selectionUpdate', ({ editor }) => {
    const { from, to } = editor.state.selection;
    awareness.setLocalStateField('cursor', {
      anchor: from,
      head: to,
    });
  });
  
  // Listen for remote cursor changes
  awareness.on('change', () => {
    const states = awareness.getStates();
    updateRemoteCursors(states);
  });
  
  // Clean up stale cursors (user closed tab without proper disconnect)
  awareness.on('change', ({ removed }) => {
    removed.forEach(clientId => removeRemoteCursor(clientId));
  });
}

// y-websocket handles binary Yjs sync messages automatically
// Custom messages for application-level features:

type WSMessage = 
  | { type: 'sync'; data: Uint8Array }          // Yjs sync protocol
  | { type: 'awareness'; data: Uint8Array }     // Cursor/presence
  | { type: 'save-version'; title?: string }    // Snapshot current state
  | { type: 'restore-version'; versionId: string }
  | { type: 'comment-add'; comment: CommentData }
  | { type: 'permission-change'; userId: string; permission: string };

import { useEditor } from '@tiptap/react';
import Collaboration from '@tiptap/extension-collaboration';
import CollaborationCursor from '@tiptap/extension-collaboration-cursor';
import * as Y from 'yjs';
import { WebsocketProvider } from 'y-websocket';

function CollaborativeEditor({ docId }: { docId: string }) {
  const ydoc = useMemo(() => new Y.Doc(), []);
  
  const provider = useMemo(() =>
    new WebsocketProvider(WS_URL, docId, ydoc, {
      connect: true,
      // Reconnect with exponential backoff
      maxBackoffTime: 10000,
    }),
    [docId, ydoc]
  );
  
  const editor = useEditor({
    extensions: [
      StarterKit.configure({ history: false }), // Disable default history!
      Collaboration.configure({ document: ydoc }),
      CollaborationCursor.configure({
        provider,
        user: { name: currentUser.name, color: userColor },
      }),
      // ... other extensions
    ],
  });
  
  // Connection status indicator
  const [status, setStatus] = useState<'connected' | 'connecting' | 'disconnected'>('connecting');
  
  useEffect(() => {
    provider.on('status', ({ status }: { status: string }) => {
      setStatus(status as any);
    });
    
    return () => {
      provider.destroy();
      ydoc.destroy();
    };
  }, [provider, ydoc]);
  
  return (
    <div>
      <ConnectionStatus status={status} />
      <CollaboratorAvatars provider={provider} />
      <EditorContent editor={editor} />
    </div>
  );
}

import { IndexeddbPersistence } from 'y-indexeddb';

// Persist Yjs doc to IndexedDB for offline editing
const indexeddbProvider = new IndexeddbPersistence(docId, ydoc);

indexeddbProvider.on('synced', () => {
  console.log('Local data loaded from IndexedDB');
  // Now connect to server — Yjs will automatically merge
  // local offline changes with server state
});

// The magic: Yjs merge is commutative
// Offline edits + server edits → deterministic merge
// No manual conflict resolution needed!

// Remote cursors rendered as ProseMirror decorations
function renderCursor(user: { name: string; color: string }, position: number) {
  return Decoration.widget(position, () => {
    const cursor = document.createElement('span');
    cursor.className = 'collaboration-cursor';
    cursor.style.borderLeft = `2px solid ${user.color}`;
    
    const label = document.createElement('div');
    label.className = 'collaboration-cursor-label';
    label.style.backgroundColor = user.color;
    label.textContent = user.name;
    
    // Auto-hide label after 2 seconds of inactivity
    label.style.opacity = '1';
    setTimeout(() => { label.style.opacity = '0'; }, 2000);
    
    cursor.appendChild(label);
    return cursor;
  });
}

// CSS for smooth cursor animation
// .collaboration-cursor {
//   position: relative;
//   margin-left: -1px;
//   border-left: 2px solid;
//   pointer-events: none;
//   transition: top 0.1s ease-out; /* Smooth cursor movement */
// }

import * as Y from 'yjs';

// Create a version snapshot
function createVersion(ydoc: Y.Doc, title: string): Uint8Array {
  return Y.encodeStateAsUpdate(ydoc);
  // Store this Uint8Array in the database
}

// Restore a version (for preview)
function previewVersion(snapshot: Uint8Array): Y.Doc {
  const previewDoc = new Y.Doc();
  Y.applyUpdate(previewDoc, snapshot);
  return previewDoc;
  // Render in a read-only TipTap instance
}

// Diff two versions
function diffVersions(older: Uint8Array, newer: Uint8Array): string {
  // Apply both to separate docs, extract text, run diff algorithm
  const oldDoc = new Y.Doc();
  const newDoc = new Y.Doc();
  Y.applyUpdate(oldDoc, older);
  Y.applyUpdate(newDoc, newer);
  // ... text diff logic
}

// For documents with 100K+ characters:

// 1. Lazy loading: don't render the entire doc
// Split into "pages" or "blocks" (Notion-style)
interface Block {
  id: string;
  type: 'paragraph' | 'heading' | 'image' | 'table';
  ydoc: Y.Doc; // Each block has its own CRDT doc
}

// 2. Throttle remote updates to reduce re-renders
const throttledApply = throttle((update: Uint8Array) => {
  Y.applyUpdate(ydoc, update);
}, 50); // Max 20 updates/second from remote

// 3. Debounce save to server
const debouncedSave = debounce(() => {
  const update = Y.encodeStateAsUpdate(ydoc);
  api.saveDocument(docId, update);
}, 2000); // Save every 2 seconds of inactivity

ydoc.on('update', debouncedSave);

function useEditorPermissions(docId: string, userId: string) {
  const permission = useDocPermission(docId, userId);
  
  return {
    editable: permission === 'edit',
    canComment: permission === 'edit' || permission === 'comment',
    canView: true,
    
    // Dynamically toggle editor editability
    editorOptions: {
      editable: permission === 'edit',
      // View-only users still see cursors and real-time changes
      // but their input is ignored
    }
  };
}