Recipe
Realtime Architecture
WebSocket-first design with Redis pub/sub for horizontal scale.
Overview
Meridian's realtime layer uses a single WebSocket gateway backed by Redis pub/sub. Every server instance subscribes to the same channels, so a message published from one node reaches all connected clients regardless of which node they're pinned to.
Connection Flow
- Client opens
wss://api.getnimbus.net/wswith an auth token. - Gateway validates the token and upgrades the connection.
- Server subscribes the socket ID to
user:{id}and any active room channels. - Heartbeat pings every 15s; stale sockets are pruned after 30s of silence.
Pub/Sub Topology
channel: user:{id} → direct messages, notifications
channel: room:{id} → group chat, presence
channel: system:broadcast → maintenance alerts, feature flags
Horizontal Scaling
Each gateway instance maintains its own WebSocket connections. When a message must be delivered, the publishing instance pushes to Redis. Every other instance receives the message and forwards it to any locally connected socket subscribed to that channel. No sticky sessions required.
Message Envelope
{
"type": "event|ack|error",
"channel": "room:abc123",
"payload": { ... },
"ts": "2026-05-26T12:00:00Z",
"seq": 142
}