Debug This Architecture

This architecture contains several critical flaws that will prevent it from functioning as a collaborative editor, likely resulting in data loss, massive latency, and immediate scaling failures.

Here is a breakdown of the failure modes, race conditions, and bottlenecks, along with architectural fixes.

---

1. Synchronization & Concurrency (The "Split Brain" Problem)

Failure Mode: Client-Side Timestamp LWW (Last-Write-Wins) Using client-side timestamps for conflict resolution is catastrophic.

• Race Condition: If User A (clock: 12:00:01) and User B (clock: 12:00:05) edit the same sentence simultaneously, User B overwrites User A completely.
• Malicious/Buggy Clients: A user with a clock set to the year 2099 will permanently lock the document state; no one else can ever overwrite their changes.
• Granularity: "Last write wins" on a whole document or paragraph level makes concurrent editing impossible. It turns the app into a turn-taking system, not a collaborative one.

Solution: CRDTs (Conflict-free Replicated Data Types) or OT (Operational Transformation) Instead of sending full HTML snapshots or raw text replacements, send operations (e.g., insert 'a' at index 5).

• Implementation: Adopt a library like Yjs or Automerge (CRDTs) or ShareDB (OT).
• Trade-off: High complexity. CRDTs increase memory usage (history required for resolution), while OT requires a central authority to sequence operations. CRDT is generally preferred for decentralized/offline-first capabilities.

---

2. Real-Time Propagation (The "Lag" Problem)

Failure Mode: Database Polling Strategy "Other servers poll PostgreSQL every 2 seconds for changes."

• Latency: Users on Server A see changes instantly. Users on Server B see them 2 seconds later. This makes real-time collaboration feel broken and leads to users overwriting each other because they are editing stale data.
• Bottleneck: As you scale to $N$ servers, the database receives $N \times (\text{Active Documents}) / 2$ queries per second just for polling. This creates a "Thundering Herd" problem that will crush PostgreSQL.

Solution: Redis Pub/Sub Backplane Since you already have Redis, use its Pub/Sub capabilities.

• Mechanism: When Server A receives a change, it publishes the delta to a Redis channel (e.g., doc_updates:UUID). All servers subscribe to channels for documents they currently have open.
• Trade-off: Increases Redis CPU/Network load. Requires logic to manage subscriptions (subscribing only when a local user opens a doc).

---

3. Load Balancing & Connections

Failure Mode: Round-Robin with WebSocket State

• Issue: Round-robin distributes users editing the same document across different servers. This forces the system to rely heavily on the Pub/Sub backplane (Solution #2) to sync them.
• Efficiency: If 10 people are editing "Doc X", and they are on 10 different servers, every keystroke must be broadcast to 10 servers.

Solution: Consistent Hashing / Application-Layer Routing Route connections based on the Document ID, not just round-robin.

• Mechanism: Use a custom load balancer (like HAProxy or Nginx with Lua) or a "Director" service that redirects the client to a specific WebSocket server node responsible for that Document ID.
• Trade-off: Hot-spotting. A viral document with 10,000 active users could overwhelm the single server assigned to it. (Mitigation: If a doc exceeds capacity, fall back to Pub/Sub across multiple nodes).

---

4. Database & Storage Patterns

Failure Mode: Write Amplification & Data Loss

• Conflict: The prompt says "Server writes change to PostgreSQL" (Step 2) AND "Documents saved as full HTML snapshots every 30s."
• Step 2 Issue: Writing to Postgres on every keystroke (WebSocket event) will destroy the database IOPS.
• Snapshot Issue: Storing full HTML snapshots is inefficient. It bloats storage and makes "undo/redo" history difficult to manage.

Solution: Write-Behind Log + Vector/Delta Storage

• Mechanism:
  1. Hot Storage (Redis): Store the temporary document state (or list of operations) in Redis.
  2. Persistence: Use a background worker to flush the consolidated state from Redis to PostgreSQL every few seconds (or when the session ends).
  3. Format: Store the document as a JSON structure (Prosemirror/Quill Delta format), not raw HTML. It is lighter and safer.
• Trade-off: If Redis crashes before flushing to Postgres, a few seconds of data might be lost (acceptable tradeoff for performance in most editors).

---

5. Caching & CDN

Failure Mode: CDN Caching API Responses "CloudFront ... caches API responses for 5 minutes."

• Critical Failure: If a user loads a document, CloudFront might serve a version from 4 minutes ago. The user edits this stale version. When they reconnect via WebSocket, their state is completely out of sync with the real-time server, causing massive merge conflicts or data corruption.

Solution: No-Cache Headers for Dynamic Data

• Mechanism: API endpoints returning document state must send Cache-Control: no-store, no-cache, must-revalidate. CloudFront should only cache static assets (JS, CSS, Images).
• Trade-off: Higher load on the origin server for initial document loads (mitigated by the Redis layer proposed in #4).

---

6. Security

Failure Mode: JWT in LocalStorage

• Vulnerability: Storing JWTs in localStorage makes them accessible to any JavaScript running on the page. If the app has a single XSS vulnerability (common in rich text editors handling HTML), an attacker can steal the token and impersonate the user.

Solution: HttpOnly Cookies

• Mechanism: Store the JWT in an HttpOnly; Secure; SameSite=Strict cookie. The browser handles sending it; JS cannot read it.
• Trade-off: Requires CSRF protection mechanisms (though SameSite cookies largely handle this now).

---

7. Scaling Strategy

Failure Mode: Partitioning by Org ID

• Bottleneck: Data skew / Hot partitions. If you land a client like "Walmart" (Org ID 1) and they have 50,000 users, and your other partition has "Mom & Pop Shop" (Org ID 2), Partition 1 will crash while Partition 2 sits idle.

Solution: Sharding by Document ID

• Mechanism: Distribute data based on hash(DocumentID). This ensures an even distribution of load regardless of the organization size.
• Trade-off: Queries that require "All documents for Org ID 1" become more expensive (scatter-gather query), but this is a read-heavy operation that can be handled by read replicas or a search index (Elasticsearch), ensuring the write-path remains performant.

Summary of Revised Architecture

1. Frontend: React + Yjs/CRDTs over WebSockets.
2. Load Balancer: Consistent Hashing based on DocID (try to group users of the same doc).
3. Backend: Node.js servers connected via Redis Pub/Sub to broadcast updates between nodes.
4. Persistence:
   • Redis: Acts as the "source of truth" for active documents (Write-Behind cache).
   • Postgres: Long-term storage. Workers flush data from Redis $\to$ Postgres asynchronously.
5. Conflict Resolution: Mathematical merging via CRDTs (no timestamps involved).
6. Security: HttpOnly Cookies.
7. Caching: CDN for assets only; API responses never cached.