Distributed Architecture

Mesh uses Redis to coordinate state and message routing across multiple server instances. This enables horizontal scaling with shared knowledge of rooms, connections, presence, and records.

How it works

When a client connects:

• The server registers the connection ID and instance ID in Redis
• Room membership and presence are stored centrally
• Messages are routed to local or remote connections using Redis pub/sub
• The Instance Manager maintains heartbeats and cleans up stale connections

Message flow

Here’s how a message to a room is delivered across instances:

What this enables

• Horizontal scaling — run as many instances as you want
• Cross-instance routing — messages go to the right server automatically
• Consistent state — shared view of room membership, presence, and records
• Automatic cleanup — presence and connection state are managed even after unexpected disconnects
• Self-healing system — the Instance Manager detects and cleans up stale connections from crashed instances

Instance Manager

The Instance Manager is a critical component that ensures system reliability in distributed deployments:

• Each server instance maintains a heartbeat in Redis with a configurable TTL
• Instances periodically check for other instances that have missed their heartbeats
• When a dead instance is detected, its connections are automatically cleaned up
• A distributed locking mechanism prevents multiple instances from cleaning up the same connections
• This ensures that even if a server crashes unexpectedly, its resources will be properly released

Mesh doesn’t require sticky sessions or load balancer affinity. Every instance is stateless and interchangeable—Redis is the source of truth. The Instance Manager further enhances this architecture by providing automatic recovery from instance failures, ensuring the system remains clean and efficient even after unexpected shutdowns.