Modular Monolith & Core Principles

Relevant source files

The following files were used as context for generating this wiki page:

• ARCHITECTURE.md
• AGENTS.md
• mobile/schema.graphql
• README.md
• assets/js/app.js

The LiveCanvas backend is designed as a Modular Monolith, a single Phoenix application with strictly enforced internal boundaries. This architecture ensures that while the system remains a single deployable unit within Kubernetes, its internal modules are decoupled to allow for independent evolution and scalability. The primary focus for the current version (V1) is product feature completeness, prioritizing account management, social interactions, and live streaming capabilities.

Sources: ARCHITECTURE.md:43-45, ARCHITECTURE.md:14-18

Architectural Fundamentals

The system follows a "one deployable per pod" strategy where every instance runs the full Elixir release. This release handles diverse workloads including GraphQL requests, REST webhooks, WebSockets for real-time interaction, and Membrane-based WebRTC media orchestration.

System Flow and Distribution

The following diagram illustrates how the modular monolith interacts with external clients and persistent storage.

Core Design Principles

• PostgreSQL as System of Record: It is the only persistent datastore. Redis is explicitly excluded from the current and future roadmap.
• Transient State Management: Transient runtime state (like active presence) is kept in supervised OTP processes, while durable facts are persisted to Postgres.
• Boundary Enforcement: Internal boundaries are enforced using the boundary library. Top-level declarations include LCApp, LC, LCWeb, LCGQL, and LCSchemas.
• Stateless Execution: Decisions are made in pure logic modules, while coordinators handle effectful side effects like database operations or PubSub broadcasts.

Sources: ARCHITECTURE.md:46-51, ARCHITECTURE.md:61-75

Domain Contexts

The backend is divided into logical contexts, each owning specific business logic and data structures. This separation prevents "leaky" abstractions where one domain manages the lifecycle of another.

Context	Ownership & Responsibilities
Accounts	Users, identity linking (OAuth, Passkeys), and session lifecycles.
Social	Follower graph, blocks, mutes, and relationship-based visibility checks.
Content	Durable content like posts, stories, and media metadata.
Live	Session lifecycle (start/end), host/viewer roles, and media orchestration.
Chat	Live chat messages, moderation, and channel-level rules.
Feed	Read-side orchestration for timelines and "who is live" surfaces.

Sources: ARCHITECTURE.md:107-160

Data Modeling and Persistence

Primary storage rules dictate that sensitive data must be handled with high integrity. For example, users records do not store primary emails or phone numbers directly; these are handled through normalized join tables to support multiple linked identities.

Identity Relationship Schema

The diagram below shows the relationship between users and their various authentication identities.

Technical Implementation Standards

GraphQL and Real-time API

GraphQL is the primary client API, utilizing Relay-first standards such as global IDs and connection-based pagination. For real-time updates—such as live chat, presence, and session countdowns—the system uses Phoenix Channels and WebSockets.

• API Protocols: GraphQL (Queries/Mutations) for durable state; WebSockets for ephemeral state.
• Security: SHA3-based token hashing for persisted secrets; mandatory re-application of viewer authorization in GraphQL node fetchers to prevent IDOR (Insecure Direct Object Reference) vulnerabilities.
• Client-Side Integration: The frontend utilizes LiveSocket for real-time connectivity, including CSRF protection and colocated hooks.

Sources: ARCHITECTURE.md:163-171, AGENTS.md:11-14, assets/js/app.js:25-31, mobile/schema.graphql:1-40

Development and Deployment

The repository includes automated setup and specific operational runbooks for production stability.

• Setup: Managed via mix setup and mix phx.server.
• Verification: Uses mix typecheck for public functions and requires milestone-based commits that bundle code with progress updates.
• Operations: Includes runbooks for staged rollouts, failover drills, and data governance.

Sources: README.md:3-16, AGENTS.md:15-35

Conclusion

The LiveCanvas Modular Monolith architecture provides a robust foundation for a high-performance streaming platform. By combining strict Elixir context boundaries with a unified deployment model and PostgreSQL-centric persistence, the system achieves a balance between development velocity and operational simplicity.

Sources: ARCHITECTURE.md:295-300