Realtime & Media Topology
Relevant source files
The following files were used as context for generating this wiki page:
The Realtime & Media Topology of LiveCanvas defines the architectural framework for handling low-latency communication, live video streaming, and synchronized session states. This system is built as a modular monolith within the Phoenix framework, utilizing WebSockets via Phoenix Channels for event broadcasting and Membrane-based WebRTC for media orchestration.
The architecture prioritizes a separation between durable state (persisted in PostgreSQL) and ephemeral state (managed via OTP processes, Phoenix Presence, and PubSub). This ensures that while session history and metadata are reliably stored, the high-frequency updates required for live interaction remain performant and distributed across the Kubernetes cluster.
Sources: ARCHITECTURE.md:86-94, ARCHITECTURE.md:144-150
Core Realtime Infrastructure
LiveCanvas utilizes Phoenix Channels as the primary transport for realtime events. This infrastructure supports chat, presence tracking, and session state synchronization. The system leverages the Erlang/Elixir BEAM VM to maintain thousands of concurrent connections within a single application runtime.
Transport and Coordination
- Phoenix Channels: Handles the WebSocket lifecycle for mobile and web clients.
- Phoenix PubSub: Provides the distributed messaging layer to broadcast events across different nodes in the Kubernetes cluster.
- Phoenix Presence: Tracks active participants in live sessions and chat rooms without requiring manual state cleanup on disconnects.
Sources: ARCHITECTURE.md:96-103, assets/js/app.js:21-27
Realtime Component Stack
| Component | Responsibility | Technology |
|---|---|---|
| Primary Transport | Realtime chat, presence, and session events | Phoenix Channels |
| State Coordination | Distributed realtime state synchronization | Phoenix PubSub / Presence |
| Media Engine | WebRTC media orchestration and streaming | Membrane Framework |
| Client Connection | Frontend WebSocket and LiveView management | Phoenix LiveSocket |
Sources: ARCHITECTURE.md:96-101, assets/js/app.js:21-25
Media Orchestration
Media handling is integrated directly into the application runtime for V1. The backend manages the lifecycle of a stream from initiation to final recording persistence.
Stream Lifecycle Flow
- Initiation: A host sends a
startLiveSessionmutation via GraphQL, creating a record in thestartingstate. - Negotiation: The backend starts a supervised session process. Media negotiation occurs over the established realtime transport.
- Broadcasting: The session transitions to the
livestate once media flow is established via Membrane/WebRTC. - Finalization: Upon session termination, the system finalizes durable records and links media assets for replay.
Sources: ARCHITECTURE.md:152-161, mobile/schema.graphql:110-140
This diagram illustrates the transition from a GraphQL intent to a stateful OTP process managing media flow.
Sources: ARCHITECTURE.md:152-161, mobile/schema.graphql:110-128
Live Session State Management
The system distinguishes strictly between durable session facts and transient runtime state to ensure system resilience and scalability.
Durable vs. Ephemeral Data
| Category | Data Points | Storage Mechanism |
|---|---|---|
| Durable | Users, Follows, Live Session Records, Chat History, Replay Metadata | PostgreSQL |
| Ephemeral | Active Participant Presence, Countdown State, Transient Media State, Typing Indicators | OTP / Presence / PubSub |
Sources: ARCHITECTURE.md:163-176
Session Status Transitions
The live_sessions entity moves through a defined state machine managed by the Live context.
- STARTING: Initial state when a host intends to go live but media is not yet negotiated.
- LIVE: Active media transmission; session is discoverable in the feed.
- ENDED: Session is concluded; durable facts are finalized for replay.
Sources: ARCHITECTURE.md:152-161, mobile/schema.graphql:273-277
Realtime API Integration
Realtime capabilities are exposed to clients through a combination of GraphQL subscriptions (via Absinthe) and Phoenix Channels.
Key API Operations
The following GraphQL mutations trigger realtime state changes:
startLiveSession: Initializes the session record.goLiveSession: Transitions the session to an active state.joinLiveSession/leaveLiveSession: Manages participant entry and exit.removeLiveChatMessage: Triggers a system event broadcast to hide moderated content.
Sources: mobile/schema.graphql:110-135, mobile/schema.graphql:153-157
This sequence shows the standard join flow for a live session topic.
Sources: ARCHITECTURE.md:100-103, ARCHITECTURE.md:244-249
Implementation Constraints
Architecture and agent guidelines impose specific rules on the implementation of the realtime layer:
- Process Topology: OTP processes are used only for explicit runtime entities (like a specific live session) or asynchronous ownership boundaries. Pure modules are preferred for synchronous logic.
- Kubernetes Scaling: Each pod in the cluster is identical and can serve all types of traffic, including media orchestration. Distributed state must be handled via PubSub to ensure consistency across pods.
- Security: Channel joins must be authorized per topic. For example,
LiveandChattopics must validate viewer eligibility and relationship-based access (e.g., checking if the viewer is blocked).
Sources: ARCHITECTURE.md:79-84, ARCHITECTURE.md:100-103, ARCHITECTURE.md:244-249, AGENTS.md:15-18
Relevant Data Structures
type LiveSession implements Node {
id: ID!
status: LiveSessionStatus!
visibility: LiveSessionVisibility!
startedAt: String
endedAt: String
host: User!
chatMessages(after: String, first: Int): ChatMessageConnection
}
The LiveSession type serves as the core entity for both durable storage and the realtime metadata broadcast.
Sources: mobile/schema.graphql:291-305
Conclusion
The Realtime & Media Topology of LiveCanvas is designed for a modular monolith deployment where Phoenix provides the high-concurrency engine required for social interaction. By leveraging Membrane for media and Phoenix for state synchronization, the system maintains a unified codebase that handles both standard API requests and complex streaming orchestration. As the system scales, the architecture allows for the extraction of media-heavy workloads into dedicated SFU pods without altering the core domain model.