Architecture

Real-time notification fan-out

The same system, assembled one layer at a time. Scroll to build it up — or use the arrow keys.

Clients hold a socket

Up to ten million clients keep a WebSocket open to an API Gateway WebSocket API. The gateway terminates the connection — we never hold a socket in our own process.

Connections are recorded

On $connect, a Lambda writes the subscription to DynamoDB keyed by topic; on $disconnect it deletes it. “All connections for topic T” becomes a single Query.

An event is published

A backend event source publishes to an SNS topic and returns immediately. The publisher is never coupled to delivery latency or to per-client throttling.

Fan-out across shards

SNS fans the event out to a set of SQS shard queues, which absorb bursts. Lambda delivery workers scale out against queue depth — not against CPU.

Deliver, then self-heal

Workers Query the connections for their shard and push via @connections POST back through the gateway to the clients. A 410 Gone deletes the stale connection on the spot; repeated failures land in a DLQ.