Live Reading Sessions
Relevant source files
The following files were used as context for generating this wiki page:
Live Reading Sessions represent the core service of the SoulSeer platform, enabling real-time spiritual consultations between clients and readers. These sessions are conducted via three primary modalities: text-based chat, voice calls, and video streaming. The system integrates real-time communication (RTC) and real-time messaging (RTM) through Agora, coupled with a per-minute billing engine and a heartbeat-driven state management system to ensure session integrity and financial accuracy.
Sources: README.md:9-11, client/src/types/index.ts:51-53, client/src/pages/reading/ReadingSessionPage.tsx:165-171
Lifecycle of a Reading Session
The lifecycle of a reading session transitions through several states, beginning with a client's request and concluding with a finalized billing transaction and optional review.
1. Request and Acceptance
A session begins when a client selects a "Reading Type" (chat, voice, or video) from a reader's profile. The system performs a "minimum balance" check (required $5.00) before allowing the request to proceed. Once the request is created, it enters a pending state, and the reader is notified via WebSocket.
Sources: client/src/pages/readers/ReaderProfilePage.tsx:64-70, server/src/routes/readings.ts:25-30, server/src/routes/readings.ts:88-93
2. Connection and Initialization
Upon reader acceptance, the session state changes to accepted. Both participants join a unique Agora channel. The server generates RTC and RTM tokens specifically for the user's ID and the session's channel name.
Sources: server/src/routes/readings.ts:182-190, client/src/pages/reading/ReadingSessionPage.tsx:431-440
3. Active Session and Heartbeats
Billing begins when the session state moves to active. While the session is live, the client-side application sends a heartbeat every 30 seconds to the /api/readings/:id/heartbeat endpoint. This prevents the billing service from prematurely ending the session due to a "grace period" expiration.
Sources: server/src/routes/readings.ts:316-324, client/src/pages/reading/ReadingSessionPage.tsx:556-562
4. Finalization
Sessions can be ended manually by either participant or automatically by the server if the client's balance is exhausted. The completed state triggers the final calculation of durationSeconds, totalCharged, and readerEarned.
Sources: server/src/routes/readings.ts:373-390, client/src/pages/reading/ReadingSessionPage.tsx:625-635
Session State Transitions
The following diagram illustrates the logical flow of a reading session from initiation to completion.
A visual representation of the session state machine and the interaction between the client and reader actions. Sources: server/src/routes/readings.ts:25-450, client/src/pages/reading/ReadingSessionPage.tsx:556-640
Communication Modalities
SoulSeer utilizes different Agora SDKs depending on the chosen reading type to optimize for performance and feature set.
| Type | Technology | Features |
|---|---|---|
| Chat | Agora RTM | Real-time text, message history storage in chatTranscript JSONB. |
| Voice | Agora RTC | Real-time audio tracks, audio visualization, mute controls. |
| Video | Agora RTC | Real-time video/audio tracks, local/remote video rendering, camera toggle. |
Sources: client/src/pages/reading/ReadingSessionPage.tsx:165-215, server/src/routes/readings.ts:456-465, client/src/types/index.ts:71
Chat Message Synchronization
For chat readings, messages are sent via the API and broadcasted through WebSocket and Agora RTM. The server appends these messages to the reading's chatTranscript field in the database for persistence.
Sources: server/src/routes/readings.ts:453-485, client/src/pages/reading/ReadingSessionPage.tsx:603-610
Billing and Financial Logic
The billing system is designed for high precision, calculating costs per minute and splitting revenue between the reader and the platform.
Financial Parameters
- Minimum Entry Balance: $5.00 (500 cents).
- Revenue Split: 70% to Reader, 30% to Platform.
- Billing Frequency: Incremental deductions occur via a backend
billingServicewhile the session isactive.
Sources: README.md:104-106, server/src/routes/readings.ts:18, server/src/routes/readings.ts:398-405
Transaction Sequence
Sequence of financial operations during a live session. Sources: server/src/routes/readings.ts:373-445, client/src/pages/reading/ReadingSessionPage.tsx:625-645
API Endpoints for Readings
The following endpoints manage the state and data of live sessions.
| Endpoint | Method | Access | Description |
|---|---|---|---|
/api/readings/on-demand | POST | Client | Requests a new session. Validates reader status and client balance. |
/api/readings/:id/accept | POST | Reader | Accepts a pending request. Moves state to accepted. |
/api/readings/:id/start | POST | Participant | Starts the billing timer and moves state to active. |
/api/readings/:id/heartbeat | POST | Participant | Updates lastHeartbeat to keep session alive in the billing engine. |
/api/readings/:id/end | POST | Participant | Finalizes duration and processes balance transfers. |
/api/readings/:id/message | POST | Participant | Appends a message to the chat transcript. |
Sources: server/src/routes/readings.ts:25, server/src/routes/readings.ts:153, server/src/routes/readings.ts:316, server/src/routes/readings.ts:348, server/src/routes/readings.ts:373, server/src/routes/readings.ts:453
Summary
Live Reading Sessions integrate complex real-time communication with a robust financial ledger. By utilizing a state-machine approach (pending -> accepted -> active -> completed), the platform ensures that readers are paid accurately for their time and clients are charged precisely for the minutes consumed. The architecture relies heavily on Agora for media transmission and WebSocket/Heartbeats for state synchronization.
Sources: server/src/routes/readings.ts:373-445, client/src/pages/reading/ReadingSessionPage.tsx:431-562