Real-time Application Rules for Claude Code

# Real-time Application Rules for Claude Code

# Real-time Application Rules

## WebSocket Architecture
- WebSocket server separate from REST API — different scaling characteristics
- Connection state stored in Redis — not in memory (multiple server instances)
- Heartbeat/ping-pong every 30s to detect dead connections
- Reconnection logic client-side with exponential backoff + jitter
- Message acknowledgment system — client confirms receipt for critical messages

```typescript
// Server-sent heartbeat
const HEARTBEAT_INTERVAL = 30_000;
ws.on('open', () => {
  const interval = setInterval(() => {
    if (ws.readyState === WebSocket.OPEN) ws.ping();
    else clearInterval(interval);
  }, HEARTBEAT_INTERVAL);
});
ws.on('pong', () => { ws.isAlive = true; });
```

## Pub/Sub Pattern
- Redis Pub/Sub or Redis Streams for broadcasting across multiple server nodes
- Channel naming: `{resource}:{id}:{event}` — e.g., `order:123:updated`
- Fan-out: server subscribes to Redis, broadcasts to all connected clients for that resource
- Presence: track who's online with Redis sorted sets (score = last seen timestamp)

## Message Reliability
- At-least-once delivery for critical events — idempotent handlers required
- Message sequence numbers to detect gaps in delivery
- Offline message queue: store messages for disconnected clients, deliver on reconnect
- Message TTL — don't deliver stale messages (configurable per message type)

## State Synchronization
- Optimistic updates client-side + server confirmation
- Conflict resolution strategy: last-write-wins vs operational transform (for collaborative editing)
- Full state sync on reconnect — don't trust client's stale state
- Differential sync for large objects — don't resend the whole object on every change