Project Introduction & Setup

Relevant source files

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

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

LiveCanvas is a Phoenix/Elixir-based modular monolith designed to support real-time media, social interactions, and live streaming. The system provides a robust backend for account management, follower graphs, and live session orchestration, primarily exposed through a Relay-first GraphQL API and Phoenix Channels.

The project is structured to scale within Kubernetes environments, where each pod runs the same Elixir release capable of handling GraphQL requests, WebSockets, background jobs, and Membrane-based WebRTC media orchestration.

Sources: ARCHITECTURE.md:10-18, ARCHITECTURE.md:76-83

System Architecture Overview

The backend follows a modular monolith architecture with strict internal boundaries enforced by the boundary library. It prioritizes PostgreSQL as the sole persistent datastore and utilizes OTP processes for transient runtime state and asynchronous ownership.

Core Architecture Principles

• Modular Monolith: One Phoenix application with internal boundaries (e.g., LC.Accounts, LC.Social).
• Persistent Storage: PostgreSQL is the system of record for all durable facts; Redis is explicitly excluded.
• Real-time Coordination: Uses OTP, Phoenix PubSub, and Phoenix Presence for ephemeral state like active participant presence and countdowns.
• API Strategy: GraphQL is the primary client API, while WebSockets (Phoenix Channels) handle chat, presence, and live session state.

Sources: ARCHITECTURE.md:41-55, ARCHITECTURE.md:120-130

The following diagram illustrates the high-level request flow and component interaction:

Development Setup

The project requires Elixir and the Phoenix framework. Standard setup involves installing dependencies and configuring the database.

Getting Started

1. Dependency Installation: Run mix setup to install backend dependencies and set up the environment.
2. Server Execution: Start the server using mix phx.server or iex -S mix phx.server for an interactive shell.
3. Local Access: The web interface is accessible at localhost:4000.

Sources: README.md:3-8

Mobile Development

The mobile component is an Expo-based React Native application located in the mobile/ directory.

Command	Description
pnpm install	Install mobile dependencies
npm run start	Start Expo development server with clear cache
npm run ios	Start the application on iOS simulator
npm run android	Start the application on Android emulator

Sources: mobile/package.json:5-10

Backend Conventions & Standards

The backend adheres to specific technical standards to ensure data integrity and security across all modules.

Data Standards

• Identifiers: Relational tables use bigint primary keys combined with :entropy_id (UUIDv7) generated by Postgres.
• Timestamps: All timestamps must use :utc_datetime_usec.
• Hashing: Token secrets are persisted using SHA3-based hashing instead of SHA-2.
• Typing: Public functions require typespecs; verification is performed via mix typecheck.

Sources: AGENTS.md:3-10

GraphQL API Design

The API follows Relay-first conventions, ensuring efficient pagination and object fetching.

Component	Convention
Pagination	Cursor-based pagination using edges and pageInfo.
Global IDs	Use of globally refetchable IDs for the node interface.
Security	Viewer authorization re-applied in node fetchers and child resolvers to prevent IDOR (CWE-639).

Sources: AGENTS.md:11-13, mobile/schema.graphql:16-19

Core Domain Contexts

The application is logically divided into several key contexts that own specific business logic and data models.

Context	Responsibility
Accounts	User state, auth lifecycle, linked identities (OAuth, Passkeys), and verification.
Social	Follow relationships, blocks, mutes, and relationship-based visibility checks.
Content	Posts (Standard/Story), media metadata, and durable content records.
Live	Live session lifecycle (starting, live, ended), host/viewer roles, and transitions.
Chat	Live chat messages, moderation, and channel-level interaction rules.

Sources: ARCHITECTURE.md:118-160

Authentication Flow

The system supports multiple login methods (email, phone, Google, Apple, Passkeys) which are resolved to a normalized identity and mapped to a single user account.

Project Summary

LiveCanvas is architected as a modular Elixir system that balances high-performance real-time features (via WebRTC and WebSockets) with durable social data management (via PostgreSQL). By enforcing strict boundaries and following Relay-first GraphQL standards, the project provides a scalable foundation for live streaming and social interaction features.

Sources: ARCHITECTURE.md:41-48, ARCHITECTURE.md:275-285