Live Sessions Context
Relevant source files
The following files were used as context for generating this wiki page:
The Live Sessions Context is a core domain within the LiveCanvas backend responsible for managing the lifecycle, state, and orchestration of real-time streaming events. It handles transitions from initial intent to "live" status, manages host and viewer roles, and facilitates the integration with media processing services for recording and replays.
This context operates as part of a modular monolith, utilizing Phoenix Channels for real-time broadcasts and PostgreSQL for durable state persistence. It works in close coordination with the Chat context for messaging and the Feed context for discovery of active sessions.
Sources: ARCHITECTURE.md:126-133, ARCHITECTURE.md:162-171
Architectural Overview
The Live context is designed to handle both durable facts (stored in Postgres) and ephemeral runtime state (managed via OTP processes). The system uses a supervised session process to maintain the active state of a live stream, which is started or located when a host initiates a session.
Session Lifecycle Flow
The lifecycle of a live session follows a specific progression of states to ensure media negotiation and viewer synchronization.
Data Components
| Component | Description | Persistence |
|---|---|---|
| LiveSession Record | Stores host ID, status, visibility, and timestamps. | PostgreSQL |
| Supervised Process | Manages transient media state and active coordination. | OTP / Memory |
| Presence | Tracks active participant lists and join/leave events. | Phoenix Presence |
| PubSub | Facilitates countdown broadcasts and state transitions. | Phoenix PubSub |
| Media Assets | Stores references to recording metadata and processing states. | PostgreSQL |
| Sources: ARCHITECTURE.md:183-195, ARCHITECTURE.md:280-286 |
API and Mutations
The Live Sessions Context is exposed primarily through the GraphQL API for management operations and Phoenix Channels for real-time updates.
GraphQL Operations
The following mutations control the session state and participant interactions:
| Mutation | Description | Input Requirements |
|---|---|---|
startLiveSession | Initializes a session record in the STARTING state. | visibility (PUBLIC/FOLLOWERS) |
goLiveSession | Transitions a session to the LIVE state after media setup. | liveSessionId |
joinLiveSession | Allows a viewer to enter an active session. | liveSessionId |
leaveLiveSession | Records a participant's exit from the session. | liveSessionId |
endLiveSession | Finalizes the session and optionally links media assets. | liveSessionId, recordingMediaAssetId |
| Sources: mobile/schema.graphql:73-82, mobile/schema.graphql:391-402 |
Visibility and Authorization
Access to live sessions is governed by the Social context. Authorization rules ensure that:
- Private sessions are only accessible to accepted followers.
- Blocked users are strictly prohibited from joining or viewing replays.
- Visibility snapshots are captured at the start of the session to maintain consistency.
Sources: ARCHITECTURE.md:315-325, ARCHITECTURE.md:283
Technical Implementation Details
Data Model: LiveSession
The LiveSession object is the central entity within this context, implementing the Relay Node interface.
type LiveSession implements Node {
id: ID!
status: LiveSessionStatus!
visibility: LiveSessionVisibility!
startedAt: String
endedAt: String
insertedAt: String!
host: User!
recordingMediaAsset: LiveSessionRecordingMediaAsset
chatMessages(after: String, first: Int): ChatMessageConnection
}
Sources: mobile/schema.graphql:404-416
Real-time Orchestration
The backend utilizes Membrane-based WebRTC media orchestration within the main application runtime. While v1 runs media tasks inside the main release pods, the architecture allows for future expansion into dedicated SFU (Selective Forwarding Unit) pods if scaling requirements dictate.
Sources: ARCHITECTURE.md:104-107, ARCHITECTURE.md:112-117
Mobile Integration
On the mobile client, live session interaction is facilitated via deep linking and modal routes. The runtime environment is configured to handle session-specific URLs (e.g., livecanvas-mobile://live-session) which resolve to dedicated modal components.
Sources: mobile/src/config/runtime.contract.ts:18-20, mobile/app/(modals)/live-session.tsx:8-20
Summary
The Live Sessions Context provides a robust framework for real-time engagement by combining durable PostgreSQL records for session history with high-performance Elixir processes for streaming orchestration. It ensures security through strict integration with the Social context and maintains high availability by leveraging Phoenix PubSub for distributed state coordination.