Debug This Architecture

Race Conditions

Client Clock Skew in Conflict Resolution
Client-generated timestamps for last-write-wins can fail due to clock skew across devices, where one client's clock lags or leads, causing incorrect overwrite ordering even if changes were logically sequential.[21][27][32] This leads to lost edits nondeterministically.
Solution: Replace client timestamps with server-assigned monotonic counters or UUIDs from a central authority like PostgreSQL sequences.
Trade-offs: Adds server-side sequencing latency (1-5ms) but eliminates skew; requires all changes to route through DB first, increasing write load.[14]

Cross-Server Update Races
When multiple servers poll PostgreSQL every 2 seconds, they may detect the same change batch simultaneously, leading to duplicate broadcasts or missed sequencing in WebSocket clients.[6] Polling windows create TOCTOU (time-of-check-to-time-of-use) gaps.
Solution: Use PostgreSQL LISTEN/NOTIFY for push notifications on change rows instead of polling.
Trade-offs: Reduces DB load and latency (sub-second vs 2s) but couples servers to DB events; notify storms possible under high churn.[1]

Failure Modes

WebSocket Connection Loss on Server Failure
Each server holds its own WebSockets; server crash drops all connected clients' sessions, forcing reconnects and potential data loss if Redis sessions aren't perfectly synced.[3][8][34] Load balancer round-robin lacks sticky sessions, exacerbating drops.
Solution: Implement sticky sessions via load balancer cookies or IP hashing, plus Redis pub/sub for cross-server broadcasting (e.g., Socket.IO Redis adapter).[23]
Trade-offs: Sticky improves reliability but risks uneven load/hotspots; pub/sub adds ~10-50ms latency and Redis dependency.[5]

PostgreSQL Write Overload
Every keystroke writes to PostgreSQL from the connected server, overwhelming the DB under concurrent edits (e.g., 100 users/doc at 5 changes/sec).[22][28][33] No write buffering leads to connection pool exhaustion.
Solution: Buffer changes in Redis (server-local queues), batch-write to PG every 100ms or 50 changes; use read replicas for non-critical queries.[3]
Trade-offs: Buffering risks minor data loss on crash (mitigate with AOF persistence) but cuts DB writes 80-90%; adds reconciliation logic.[22]

Stale CDN-Cached API Responses
CloudFront caches API responses 5 minutes, serving outdated document states or changes to clients, especially read-heavy ops like load/join.[25] Invalidation isn't automatic for DB writes.
Solution: Exclude dynamic APIs from CDN caching or use short TTL (10s) with Cache-Control: no-cache headers; invalidate on document writes via CloudFront invalidations.[30]
Trade-offs: No-cache boosts origin load 10x but ensures freshness; invalidations cost API calls and have quotas.[36]

JWT XSS Vulnerability
JWTs in localStorage are readable by XSS scripts, allowing token theft and full account takeover if frontend has any injection flaw.[24][29] 24h expiry doesn't prevent session hijack.
Solution: Store JWT in httpOnly cookies (backend-set), use short-lived access tokens (15min) refreshed via refresh tokens.
Trade-offs: Cookies enable CSRF (mitigate with tokens) but block XSS access; adds backend refresh endpoint load.[35]

Document Snapshot Inconsistency
30s HTML snapshots may capture mid-edit state during active collaboration, leading to corrupt restores or lost granularity on load/reconnect.[26][31] Full snapshots bloat storage without op logs.
Solution: Store incremental ops alongside snapshots (e.g., Yjs-style log), replay on load; snapshot every 5min during activity.[31]
Trade-offs: Ops add storage/query complexity (need GC) but enable history/undo; replay latency scales with churn (limit to 5min ops).[9]

Scaling Bottlenecks

Polling DB Load Explosion
N servers polling every 2s = N/2 queries/sec baseline, exploding to 100s/sec per doc with high activity; kills read replicas.[10]
Solution: Switch to Redis pub/sub for change notifications across servers, with PG as source-of-truth.
Trade-offs: Redis adds single-point failure (use cluster) but drops polls 100x, enabling 10k+ servers.[3]

Per-Server WebSocket Limits
Node.js handles ~5k-10k WS/server; beyond requires 100s of instances, straining Redis for sessions if stateful.[8][13]
Solution: Stateless WS with Redis/Kafka pub/sub; partition docs by org ID across servers.[3][18]
Trade-offs: Pub/sub network overhead (20-100ms) but true horizontal scale to millions; eventual consistency.[5]

DB Partitioning Gaps
Org ID partitioning helps but hot orgs (e.g., large teams) still overload single shards; no sharding mentioned.[39]
Solution: Add document ID hashing for sub-partitioning, with PG Citus for horizontal sharding.
Trade-offs: Citus adds 2x latency/join complexity but scales writes linearly; migration disruptive.[22]