01 — Architecture Overview
1. System Context
The platform exposes two planes with strictly separated concerns:
- Control plane — business logic: authentication, room management, signaling, presence, notifications, analytics, configuration, (future) billing. Stateless, cheap to scale, latency-tolerant (tens of ms).
- Media plane — real-time audio: SFU cluster, TURN/STUN cluster, recording, media monitoring. Stateful per-session, bandwidth/CPU-bound, latency-critical (sub-ms forwarding decisions). Scales independently of the control plane.
The two planes meet at exactly one seam: the Media Coordination function (room-to-SFU-node assignment and access tokens). Business logic never touches RTP; media nodes never touch business data.
2. Overall Architecture Diagram
Key properties of this shape:
- Clients speak to two endpoints only: the API Gateway (REST + WebSocket signaling) and the media plane directly (SRTP/UDP to SFU, TURN relay as fallback). Media bypasses the gateway — an L7 HTTP gateway must never sit in the RTP path.
- All inter-service coupling below the gateway is asynchronous where possible (Kafka events). Synchronous calls exist only where a user is waiting on the answer (auth check, room join, TURN credential issue).
- Redis is the ephemeral-state fabric: presence, signaling pub/sub fan-out, TURN credential cache, rate-limit counters. Nothing in Redis is a source of truth; everything is reconstructible.
3. Component Diagram
4. Control Plane / Media Plane Contract
| Concern | Control plane | Media plane |
|---|---|---|
| Who joins a room | Decides (auth + room ACL) | Enforces via signed media token only |
| Which SFU node hosts a room | Decides (media coordinator) | Reports capacity/health |
| RTP forwarding, simulcast, speaker detection | Never sees packets | Owns entirely |
| Scaling signal | RPS, connection count | Bandwidth, CPU, subscriber count |
| Deployment cadence | Frequent (rolling) | Careful (drain-then-replace; live sessions) |
The only artifacts that cross the boundary:
- Media access token — short-lived signed JWT minted by the control plane (Room Service via LiveKit-compatible grant), validated by the SFU.
- TURN credential — short-lived HMAC credential minted by TURN Management, validated by Coturn against a shared secret (no runtime call from Coturn back to us).
- Webhooks/events — SFU emits participant/track/room events consumed by the control plane and republished onto Kafka.
This contract is what makes independent scaling and independent failure domains possible: the control plane can be fully redeployed without dropping a single audio stream, and an SFU node failure never corrupts business state.
5. Multi-Region Shape
Each region runs a full media plane (SFU + TURN clusters) and a signaling tier. The control plane's source-of-truth data (PostgreSQL, Kafka) runs primary-region with cross-region replicas; Redis presence is region-local with a global aggregation view. Clients are routed to the nearest region by GeoDNS/anycast; a room is pinned to one SFU region (chosen at creation by creator locality or tenant policy) so all its participants converge on the same media cluster. Details in 09 — Scalability, HA & DR.