Real-Time & WebRTC Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The Real-Time & WebRTC Architecture in SoulSeer enables instantaneous communication between clients and readers through three primary modalities: text-based chat, voice calls, and video streaming. This system is built upon a hybrid infrastructure utilizing WebSockets for state signaling and system events, and the Agora SDK for high-performance media streaming and real-time messaging.
This architecture ensures that spiritual consultations are billed accurately per minute, maintain high availability even during network fluctuations, and provide immediate feedback on connection status and account balances.
System Components
The real-time ecosystem is divided into specialized services handling different aspects of the live session.
WebSocket Infrastructure
The WebSocket system serves as the backbone for platform-level events. It manages client connectivity states and delivers critical system notifications that do not require the high-bandwidth capabilities of WebRTC.
- Server-Side (
WebSocketService): Manages a map of authenticated user IDs to active socket sets, allowing for targeted event dispatching. It includes a heartbeat mechanism to prune stale connections every 30 seconds. - Client-Side (
WebSocketContext): Provides a global provider that handles automatic reconnection with exponential backoff and provides a subscription model for components to listen for specific event types.
Sources: server/src/services/websocket-service.ts:15-30, client/src/contexts/WebSocketContext.tsx:21-35
Agora Media Integration
For the actual reading content (audio/video/chat), the platform integrates Agora’s RTC (Real-Time Communication) and RTM (Real-Time Messaging) SDKs.
- RTC (Real-Time Communication): Used for Voice and Video readings. It handles hardware access (camera/microphone), encoding, and low-latency transmission.
- RTM (Real-Time Messaging): Specifically used for the "Chat" reading type to provide reliable, low-latency text delivery separate from the system's general WebSockets.
Sources: client/src/pages/reading/ReadingSessionPage.tsx:430-485, README.md:28
Data Flow & Signaling
The following diagram illustrates the lifecycle of a reading session, from initialization to termination.
The flow ensures that media tokens are only generated upon valid session acceptance and that billing state is synchronized across all participants via WebSocket signals.
Sources: client/src/pages/reading/ReadingSessionPage.tsx:425-450, server/src/services/websocket-service.ts:36-42, client/src/pages/reading/ReadingSessionPage.tsx:505-515
Real-Time Event Types
The system uses a standardized messaging format for all WebSocket communications.
| Event Type | Direction | Description |
|---|---|---|
reading:accepted | Server -> Client | Notifies the client that a reader has accepted their request. |
reading:ended | Server -> Both | Terminates the UI session and triggers the post-session summary. |
reading:insufficient_balance | Server -> Client | Warning sent when the user's balance cannot cover much more time. |
reading:partner_disconnected | Server -> Both | Sent when one participant's socket closes during an active reading. |
reading:partner_reconnected | Server -> Both | Sent when a participant recovers their connection within the grace period. |
Sources: client/src/contexts/WebSocketContext.tsx:10-15, client/src/pages/reading/ReadingSessionPage.tsx:517-575
Session Management & Recovery
The ReadingSessionPage implements complex logic to handle the volatile nature of mobile and web connections.
Connection State Machine
The client tracks four distinct connection states to provide user feedback:
- Connecting: Initializing Agora SDK and fetching tokens.
- Connected: Active media stream and heartbeat.
- Reconnecting: Triggered by
reading:partner_disconnectedor local socket drops; the system pauses the billing timer and waits (up to 2 minutes) for recovery. - Disconnected: Final state if reconnection fails or the session is manually ended.
Sources: client/src/pages/reading/ReadingSessionPage.tsx:29-33, client/src/pages/reading/ReadingSessionPage.tsx:685-700
Heartbeats and Billing Safety
To prevent "ghost sessions" where a user is billed for time they aren't connected, the architecture employs a multi-layered safety check:
- Client Heartbeat: The client sends a POST request to
/api/readings/:id/heartbeatevery 30 seconds while the session is live. - Server Sweeper: The billing service (started in
index.ts) monitors these heartbeats and automatically terminates sessions that haven't checked in, protecting the user's balance.
Sources: client/src/pages/reading/ReadingSessionPage.tsx:507-513, server/src/index.ts:162-164
Security and Authorization
All real-time connections are strictly authenticated using Auth0 JWTs.
- WebSocket Upgrade: The
WebSocketServiceintercepts the HTTPupgraderequest, extracts a token from the query parameters, and verifies it against Auth0's JWKS (JSON Web Key Set) before allowing the connection. - Agora Tokens: Tokens for voice/video are generated server-side with specific permissions for a single channel name and expiration time, preventing unauthorized users from eavesdropping on sessions.
- CSP Headers: The server enforces strict Content Security Policies allowing connections only to specific Agora and Stripe domains.
Sources: server/src/services/websocket-service.ts:56-85, server/src/index.ts:33-54, client/src/pages/reading/ReadingSessionPage.tsx:432-440
Summary
The SoulSeer Real-Time & WebRTC Architecture combines the flexibility of WebSockets with the robustness of Agora to deliver a seamless spiritual consultation experience. By decoupling system signaling (WebSockets) from media transmission (Agora RTC/RTM), the platform achieves high reliability, accurate per-minute billing, and a responsive UI that keeps users informed of their connection and financial status in real time.