Debug This Architecture

I'll analyze this collaborative document editor architecture systematically, identifying critical issues and proposing solutions.

CRITICAL FAILURE MODES

1. Cross-Server Synchronization Gap (Major Issue)

Problem: Users connected to different servers won't see each other's changes until polling catches up.

• Server A user makes change at 10:00:01
• Server B user makes change at 10:00:02
• Server B doesn't know about Server A's change until 10:00:04 (polling cycle)
• Data loss occurs at 10:00:04 when Server B overwrites with stale data

Solution: Implement a shared message bus (Redis Pub/Sub or Apache Kafka)

// Replace polling with pub/sub
redis.subscribe('doc-changes', (message) => {
  // Broadcast to all WS clients on this server
  broadcastToClients(JSON.parse(message));
});

Trade-offs: Adds infrastructure complexity but ensures real-time consistency across servers

2. Client Clock Inconsistency (Critical Race Condition)

Problem: "Last-write-wins with client timestamps" is fundamentally flawed due to clock drift.

• User A (clock = 6:00 PM) makes edit
• User B (clock = 6:05 PM) makes concurrent edit
• User A's edit gets overwritten despite happening first chronologically

Solution: Use Lamport timestamps or Operational Transformation (OT)

// Lamport timestamp approach
const lamportClock = Math.max(localClock, incomingTimestamp) + 1;
const operation = { 
  content: newContent,
  timestamp: Date.now(),
  serverId: serverId,
  sequenceNumber: lamportClock
};

Trade-offs: More complex logic but ensures logical ordering regardless of physical clocks

SCALING BOTTLENECKS

3. Database Write Bottleneck

Problem: Every character change hits PostgreSQL immediately → database saturation

• 1000 concurrent editors × 5 chars/sec = 5000 writes/second per document
• PostgreSQL becomes the bottleneck quickly

Solution: Operation buffering with batch commits

class OperationBuffer {
  constructor() {
    this.buffer = [];
    setInterval(this.flush, 250); // Batch every 250ms
  }
  
  addOperation(op) {
    this.buffer.push(op);
    if (this.buffer.length > 50) this.flush(); // Force flush
  }
}

Trade-offs: Potential data loss on crashes vs. improved throughput

4. WebSocket Connection Limitations

Problem: Each server maintains N connections locally, no cross-server sharing

• Server restart disconnects all clients
• No failover capability
• Memory pressure on individual servers

Solution: Externalize WebSocket management with Pusher/Rocket.Chat or Redis-backed connection registry

// Shared connection registry
const connections = new Map();
redis.hset('server_connections', serverId, JSON.stringify(connections));
// Route messages through shared bus

Trade-offs: Network overhead but enables high availability

DATA CONSISTENCY ISSUES

5. HTML Snapshot Storage Problem

Problem: Saving full HTML snapshots every 30 seconds loses granular edit history

• Cannot implement undo/redo properly
• No audit trail of who made what change
• Massive storage bloat over time

Solution: Store operational transforms, not snapshots

CREATE TABLE document_operations (
  id SERIAL PRIMARY KEY,
  doc_id UUID,
  operation_type VARCHAR(20), -- 'insert', 'delete', 'format'
  position INT,
  content TEXT,
  user_id UUID,
  timestamp TIMESTAMP,
  revision_number BIGINT
);

Trade-offs: More complex querying but preserves complete edit history

6. CDN Caching Anti-Pattern

Problem: Caching API responses for collaborative editing is dangerous

• Users get stale document state
• Real-time collaboration breaks entirely
• Cache invalidation nightmare

Solution: Cache only static assets, never dynamic content

// Only cache static assets, exclude API routes
app.get('/api/*', (req, res, next) => {
  res.set('Cache-Control', 'no-cache, no-store');
  next();
});

Trade-offs: Higher backend load but correct behavior

SECURITY VULNERABILITIES

7. JWT in localStorage XSS Risk

Problem: Storing JWT in localStorage makes it accessible to XSS scripts

• Any XSS vulnerability → account takeover
• Tokens persist even after browser close

Solution: HttpOnly cookies with SameSite protection

res.cookie('auth_token', token, {
  httpOnly: true,
  secure: true,
  sameSite: 'strict',
  maxAge: 86400000 // 24 hours
});

Trade-offs: Slightly more complex frontend handling but much more secure

ADDITIONAL ARCHITECTURE ISSUES

8. Poor Document Partitioning Strategy

Problem: Partitioning by organization ID creates hotspots

• Large organizations get bottlenecked on single shard
• Poor distribution of load

Solution: Hash-based sharding using document ID + chunking

function getShard(docId) {
  return hash(docId) % numShards; // Better distribution
}

9. Missing Operational Transformation

Problem: Simple timestamp resolution can cause document corruption

• Two users typing in same paragraph simultaneously
• Character insertion/deletion conflicts

Solution: Implement proper OT or CRDT algorithms

class TextOperation {
  apply(text) {
    // Handle insertions/deletions in correct order
    return this.operations.reduce((result, op) => {
      return op.applyTo(result);
    }, text);
  }
}

HIGH-LEVEL RECOMMENDATION

Replace the current architecture with:

• Backend: Single operational queue (Kafka/RabbitMQ) for document operations
• Sync: Operational Transformation library (ShareJS, Firebase-like service)
• Storage: Append-only log of operations + materialized views
• Caching: Smart caching of document snapshots, never live operations
• WS: Shared WebSocket cluster with proper routing

The current design will work poorly under any significant load due to fundamental synchronization flaws.