Total documents = 1M users × 10 docs/user = 10 million documents

Document storage:
- Content: 10M docs × 100 KB = 1 TB
- Metadata: 10M docs × 1 KB = 10 GB
- Operation logs: 10M docs × 50 KB avg = 500 GB
- Revisions (30-day): 10M docs × 10 revisions × 20 KB delta = 2 TB

Total storage ≈ 3.5 TB + growth buffer = ~5 TB initial

Peak concurrent users = 1M DAU × 0.1 (10% online at peak) = 100K users

Assuming 10% actively editing:
- Active editors at peak = 100K × 0.1 = 10,000 users
- Edit operations/sec = 10,000 × 1 op/sec = 10,000 ops/sec

WebSocket connections at peak = 100,000 concurrent connections

Per edit operation: ~200 bytes (operation + metadata)
Edit broadcast: 200 bytes × avg 5 collaborators = 1 KB per edit

Inbound: 10,000 ops/sec × 200 bytes = 2 MB/s
Outbound (fanout): 10,000 ops/sec × 1 KB = 10 MB/s

Total bandwidth ≈ 12 MB/s sustained, 60 MB/s at 5x peak

Document {
    id:                 UUID          // Unique document identifier
    owner_id:           UUID          // User who created the document
    title:              String        // Document title
    head_revision_id:   UUID          // Pointer to latest revision
    created_at:         Timestamp
    updated_at:         Timestamp
    content_url:        String        // Object storage URL for content
}

Operation {
    id:                 UUID          // Unique operation ID
    document_id:        UUID          // Parent document
    user_id:            UUID          // Author of the operation
    type:               Enum          // INSERT, DELETE, RETAIN
    position:           Integer       // Character position in document
    content:            String        // Text to insert (for INSERT ops)
    length:             Integer       // Characters affected (for DELETE/RETAIN)
    client_revision:    Integer       // Client's view of document version
    server_revision:    Integer       // Assigned by server after sequencing
    timestamp:          Timestamp
}

Revision {
    id:                 UUID
    document_id:        UUID
    revision_number:    Integer       // Sequential version number
    snapshot_url:       String        // Object storage URL for snapshot
    operations_range:   [start, end]  // Operation IDs included
    author_id:          UUID          // Primary contributor
    created_at:         Timestamp
    size_bytes:         Integer
}

Permission {
    id:                 UUID
    document_id:        UUID
    grantee_type:       Enum          // USER, GROUP, LINK
    grantee_id:         String        // User/group ID or link token
    role:               Enum          // VIEWER, EDITOR, ADMIN
    expires_at:         Timestamp     // Optional expiration
    created_by:         UUID
    created_at:         Timestamp
}

┌─────────────┐     1:N     ┌─────────────┐
│  Document   │────────────▶│  Revision   │
└─────────────┘             └─────────────┘
       │
       │ 1:N
       ▼
┌─────────────┐
│  Operation  │
└─────────────┘
       │
       │ 1:N
       ▼
┌─────────────┐
│ Permission  │
└─────────────┘

Endpoint: WS /api/documents/{documentId}/collaborate

// Client → Server Messages
{
    "type": "operation",
    "payload": {
        "ops": [
            { "type": "RETAIN", "length": 10 },
            { "type": "INSERT", "content": "Hello" },
            { "type": "DELETE", "length": 3 }
        ],
        "clientRevision": 42
    }
}

{
    "type": "presence_update",
    "payload": {
        "cursor": { "position": 150, "selectionEnd": 160 },
        "color": "#FF5733"
    }
}

// Server → Client Messages
{
    "type": "operation_ack",
    "payload": {
        "serverRevision": 43,
        "transformedOps": [...]  // If transformation was needed
    }
}

{
    "type": "remote_operation",
    "payload": {
        "userId": "user-456",
        "userName": "Alice",
        "serverRevision": 44,
        "ops": [...]
    }
}

{
    "type": "presence_broadcast",
    "payload": {
        "userId": "user-456",
        "userName": "Alice",
        "cursor": { "position": 200 },
        "color": "#3498DB"
    }
}

                                    ┌─────────────────────────────────────────────────────────────┐
                                    │                        Clients                               │
                                    │    (Web Browsers / Mobile Apps / Desktop Apps)               │
                                    └─────────────────────────────┬───────────────────────────────┘
                                                                  │
                                                                  │ HTTPS / WSS
                                                                  ▼
                                    ┌─────────────────────────────────────────────────────────────┐
                                    │                     Load Balancer                            │
                                    │              (Sticky Sessions for WebSocket)                 │
                                    └─────────────────────────────┬───────────────────────────────┘
                                                                  │
                              ┌───────────────────────────────────┼───────────────────────────────────┐
                              │                                   │                                   │
                              ▼                                   ▼                                   ▼
                    ┌─────────────────┐                 ┌─────────────────┐                 ┌─────────────────┐
                    │   Real-time     │                 │   Real-time     │                 │   Real-time     │
                    │    Gateway      │                 │    Gateway      │                 │    Gateway      │
                    │  (WebSocket)    │                 │  (WebSocket)    │                 │  (WebSocket)    │
                    └────────┬────────┘                 └────────┬────────┘                 └────────┬────────┘
                             │                                   │                                   │
                             └───────────────────────────────────┼───────────────────────────────────┘
                                                                 │
                    ┌────────────────────────────────────────────┼────────────────────────────────────────────┐
                    │                                            │                                            │
                    ▼                                            ▼                                            ▼
          ┌─────────────────┐                          ┌─────────────────┐                          ┌─────────────────┐
          │   Presence      │                          │  Collaboration  │                          │   Document      │
          │   Service       │                          │    Service      │                          │   Service       │
          │                 │                          │                 │                          │                 │
          │ • Cursor sync   │                          │ • OT Engine     │                          │ • CRUD ops      │
          │ • User presence │                          │ • Sequencer     │                          │ • Permissions   │
          │ • Ephemeral     │                          │ • Op Log        │                          │ • Metadata      │
          └────────┬────────┘                          └────────┬────────┘                          └────────┬────────┘
                   │                                            │                                            │
                   ▼                                            │                                            ▼
          ┌─────────────────┐                                   │                                   ┌─────────────────┐
          │     Redis       │                                   │                                   │   PostgreSQL    │
          │  (Presence)     │                                   │                                   │  (Metadata)     │
          │                 │                                   │                                   │                 │
          │ • TTL-based     │                                   │                                   │ • Documents     │
          │ • Pub/Sub       │                                   │                                   │ • Permissions   │
          └─────────────────┘                                   │                                   │ • Revisions     │
                                                                │                                   └─────────────────┘
                                                                │
                                                                ▼
                                    ┌─────────────────────────────────────────────────────────────┐
                                    │                      Message Queue                           │
                                    │                    (Kafka / Redis Pub/Sub)                   │
                                    │                                                             │
                                    │  • Operation fanout to all gateways                         │
                                    │  • Guaranteed delivery                                       │
                                    │  • Per-document topic partitioning                          │
                                    └─────────────────────────────────────────────────────────────┘
                                                                │
                                    ┌───────────────────────────┼───────────────────────────────┐
                                    │                           │                               │
                                    ▼                           ▼                               ▼
                          ┌─────────────────┐         ┌─────────────────┐             ┌─────────────────┐
                          │  Operation Log  │         │ Object Storage  │             │ Snapshot Writer │
                          │  (Append-only)  │         │    (S3/GCS)     │             │   (Background)  │
                          │                 │         │                 │             │                 │
                          │ • All ops       │         │ • Doc content   │             │ • Periodic      │
                          │ • Ordered       │         │ • Snapshots     │             │ • Compaction    │
                          │ • Immutable     │         │ • Durable       │             │ • Rev creation  │
                          └─────────────────┘         └─────────────────┘             └─────────────────┘

1. User types "Hello" in the editor

2. Client creates operation:
   { type: INSERT, position: 50, content: "Hello", clientRevision: 42 }

3. Client sends operation over WebSocket to Real-time Gateway

4. Gateway forwards to Collaboration Service

5. Collaboration Service:
   a. Validates user permission (via Document Service)
   b. Acquires lock for document (distributed lock)
   c. Transforms operation against any concurrent ops
   d. Assigns server revision number (43)
   e. Appends to Operation Log
   f. Publishes transformed op to Message Queue

6. Message Queue fans out to all subscribed Gateways

7. Each Gateway broadcasts to connected collaborators

8. Clients apply transformed operation to their local state

9. Original client receives ACK with server revision

Initial document: "Hello World"
                   01234567890

User A (at position 5): INSERT " Beautiful"   → "Hello Beautiful World"
User B (at position 5): INSERT " Amazing"     → "Hello Amazing World"

Both users started from the same state, but their operations conflict.
Without resolution, we get divergent states:
- User A sees: "Hello Beautiful World"
- User B sees: "Hello Amazing World"

How it works: Latest timestamp wins, earlier edit is discarded.

Pros:
- Simple implementation
- No complex merging

Cons:
- Data loss (user's work disappears)
- Terrible user experience
- Not suitable for collaborative editing

Verdict: ❌ NOT SUITABLE

How it works:
- Operations are transformed against concurrent operations
- A central server sequences all operations
- Each operation is adjusted based on prior operations

Example:
- User A: INSERT("Beautiful", 5)  →  arrives first  →  revision 1
- User B: INSERT("Amazing", 5)    →  arrives second →  must transform

Transformation:
- User A's op inserted 10 chars at position 5
- User B's position must shift: 5 + 10 = 15
- Transformed: INSERT("Amazing", 15)

Result: "Hello Beautiful Amazing World" (both edits preserved!)

Pros:
- Proven in production (Google Docs uses OT)
- Efficient on wire (small operation deltas)
- Central sequencer simplifies consistency

Cons:
- Complex transformation functions
- Requires central coordination (server dependency)
- Offline support is challenging

Verdict: ✅ RECOMMENDED for server-centric architecture

How it works:
- Each character has a unique, globally ordered ID
- Operations can be applied in any order
- Convergence is mathematically guaranteed

Example (simplified):
- Character IDs are tuples: (timestamp, userId, position)
- "Hello" → [(1,A,0)H, (2,A,1)e, (3,A,2)l, (4,A,3)l, (5,A,4)o]
- Insert by User A: (6,A,5)" " → automatically ordered
- Insert by User B: (6,B,5)" " → different userId, deterministic order

Pros:
- No central coordinator needed
- Works offline (sync when reconnected)
- Mathematically proven convergence

Cons:
- Higher memory overhead (metadata per character)
- Complex garbage collection
- Harder to reason about for teams

Verdict: ✅ BETTER for peer-to-peer / offline-first

Operations follow a simple model with three types:

1. RETAIN(n)  - Keep n characters unchanged
2. INSERT(s)  - Insert string s at current position
3. DELETE(n)  - Delete n characters

Example: Changing "Hello World" to "Hello Beautiful World"
Operations: [RETAIN(5), INSERT(" Beautiful"), RETAIN(6)]
            Keep "Hello", insert " Beautiful", keep " World"

The core of OT is the transform(op1, op2) function.

Given two operations that were created from the same base state:
- op1: first operation (already applied)
- op2: second operation (needs transformation)

Returns: op2' (transformed version of op2 that can be applied after op1)

Key transformations:

1. INSERT vs INSERT (both at same position):
   - Tie-breaker: lower userId wins priority
   - Loser's position shifts by winner's insert length

2. INSERT vs DELETE:
   - If insert position < delete range: delete shifts right
   - If insert position > delete range: insert shifts left
   - If insert position within delete range: insert survives

3. DELETE vs DELETE (overlapping):
   - Only delete characters not already deleted
   - Adjust ranges to avoid double-deletion

Base document: "ABCDEF" (positions: A=0, B=1, C=2, D=3, E=4, F=5)

User A operation: DELETE at position 2, length 2  →  Delete "CD"
User B operation: INSERT "XY" at position 3

Timeline:
  t0: Both users see "ABCDEF"
  t1: User A sends DELETE(2, 2)  →  Server assigns revision 1
  t2: User B sends INSERT(3, "XY") →  Needs transformation

Transformation:
- A deleted positions 2-3 ("CD")
- B wanted to insert at position 3 (which is inside deleted range)
- Decision: Insert survives at position 2 (start of deletion)
- Transformed B: INSERT(2, "XY")

Final result (both users):
- After A: "ABEF"
- After B': "ABXYEF"

                                    ┌─────────────────────────────────────────┐
                                    │           Collaboration Service          │
                                    └─────────────────────────────────────────┘
                                                         │
                                    ┌────────────────────┼────────────────────┐
                                    │                    │                    │
                                    ▼                    ▼                    ▼
                              ┌──────────┐         ┌──────────┐         ┌──────────┐
                              │Sequencer │         │Sequencer │         │Sequencer │
                              │ Doc A-M  │         │ Doc N-S  │         │ Doc T-Z  │
                              └──────────┘         └──────────┘         └──────────┘
                                    │                    │                    │
                                    │              Document Partition          │
                                    │                    │                    │
                                    └────────────────────┼────────────────────┘
                                                         │
                                                         ▼
                                              ┌─────────────────┐
                                              │  Operation Log  │
                                              │  (Per Document) │
                                              └─────────────────┘

class DocumentSequencer {
    private final Lock documentLock;
    private int currentRevision;
    private final List<Operation> pendingOps;
    private final OperationLog operationLog;
    
    public TransformResult processOperation(Operation incomingOp) {
        documentLock.lock();
        try {
            // 1. Validate operation
            validateOperation(incomingOp);
            
            // 2. Get operations since client's known revision
            List<Operation> concurrentOps = operationLog
                .getOperationsSince(incomingOp.getClientRevision());
            
            // 3. Transform against all concurrent operations
            Operation transformed = incomingOp;
            for (Operation concurrent : concurrentOps) {
                transformed = transform(transformed, concurrent);
            }
            
            // 4. Assign server revision and persist
            currentRevision++;
            transformed.setServerRevision(currentRevision);
            operationLog.append(transformed);
            
            // 5. Return result for broadcast
            return new TransformResult(transformed, currentRevision);
            
        } finally {
            documentLock.unlock();
        }
    }
}

Each document has a dedicated single-threaded event loop:
- Operations queue up and are processed in order
- No lock contention (single thread)
- Throughput: ~10,000 ops/sec per document (sufficient for 100 users at 1 op/sec each)

Pros: Simple, predictable latency
Cons: Single point of failure per document

Batch multiple operations before sequencing:
- Collect ops for 10-50ms
- Transform entire batch together
- Reduces transformation overhead

Pseudocode:
while (true) {
    List<Operation> batch = collectOpsForMs(50);
    for (Operation op : batch) {
        processOperation(op);
    }
    broadcastBatch(batch);
}

For documents with 1000+ concurrent editors:
- Divide document into regions
- Separate sequencer per region
- Cross-region operations require coordination

This is complex and rarely needed (Google Docs limits ~100 concurrent).

┌────────────────────────────────────────────────────────────────────────────┐
│                              Client Editor                                  │
│                                                                            │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐ │
│  │   Editor    │───▶│  Local Op   │───▶│  Transform  │───▶│  WebSocket  │ │
│  │   (UI)      │    │   Queue     │    │   Buffer    │    │   Client    │ │
│  └─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘ │
│        ▲                                      │                  │         │
│        │                                      │                  │         │
│        └──────────────────────────────────────┘                  │         │
│                     Apply Transformed Ops                         │         │
│                                                                   │         │
│  ┌─────────────────────────────────────────────────────────────┐ │         │
│  │                    Operation Buffer                          │ │         │
│  │                                                              │ │         │
│  │  Pending:    [op1, op2, op3]  (sent but not ACKed)          │◀┘         │
│  │  Unsynced:   [op4, op5]       (local, not yet sent)         │           │
│  │                                                              │           │
│  └─────────────────────────────────────────────────────────────┘           │
└────────────────────────────────────────────────────────────────────────────┘

Client Algorithm:
1. User makes edit → Create local operation
2. Apply optimistically to local document (instant feedback)
3. If no pending ops, send immediately
4. If pending ops exist, queue in Unsynced buffer
5. When ACK received:
   a. Remove from Pending buffer
   b. Transform Unsynced ops against any server ops
   c. Send next queued operation
6. When remote op received:
   a. Transform against all Pending ops
   b. Apply transformed op to local document
   c. Update cursor positions

Presence Update Flow:

1. User moves cursor → Client sends presence update (throttled to 100ms)
2. Real-time Gateway forwards to Presence Service
3. Presence Service:
   - Updates Redis with TTL (5 seconds)
   - Publishes to document's presence channel
4. Other clients receive cursor position
5. TTL cleanup removes stale presence (user closed tab)

Data Structure (Redis):
Key: "presence:{documentId}:{userId}"
Value: {
    "cursor": {"position": 150, "selectionEnd": 160},
    "color": "#FF5733",
    "name": "Alice",
    "lastUpdate": 1708425600
}
TTL: 5 seconds (auto-cleanup)

Sequencer Failover:
1. Detect failure (heartbeat timeout: 5s)
2. Standby acquires document lock (distributed lock)
3. Replay operation log from last checkpoint
4. Resume accepting new operations
5. Notify gateways of new sequencer endpoint

Total failover time target: < 10 seconds