Core Schema & Data Model

Relevant source files

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

• ARCHITECTURE.md
• mobile/schema.graphql
• AGENTS.md
• README.md
• mobile/src/theme/tokens.ts

The Core Schema and Data Model of LiveCanvas define the structural foundation of a modular monolith designed for high-concurrency social interactions, media sharing, and live streaming. The architecture prioritizes PostgreSQL as the single source of truth for durable facts, while leveraging Phoenix PubSub and Presence for ephemeral state. This model supports a Relay-first GraphQL API, ensuring consistent data fetching through global IDs, nodes, and cursor-based pagination.

The data model is partitioned into distinct domain boundaries: Accounts, Social, Content, Live, Chat, and Feed. This separation ensures that logic governing user identities does not bleed into live session management or feed ranking, allowing the system to scale and evolve without breaking core contracts.

Sources: ARCHITECTURE.md:46-52, ARCHITECTURE.md:126-130, AGENTS.md:9-11

Global Data Conventions

The backend enforces strict data conventions to ensure performance, security, and interoperability across the Elixir application and mobile clients.

• Primary Keys: Relational tables use bigint primary keys supplemented by an :entropy_id (UUIDv7) for external exposure.
• Timestamps: All timestamps are stored using :utc_datetime_usec to maintain microsecond precision across time zones.
• Secret Handling: Token secrets are never stored in raw form; they are persisted using SHA3-based hashing.
• API Structure: The GraphQL API follows the Relay specification, utilizing Node interfaces and connection-based pagination.

Sources: AGENTS.md:3-9, mobile/schema.graphql:19-22

Domain-Specific Models

Accounts and Identity

The Accounts domain manages user lifecycle and authentication. Unlike traditional models, users do not directly contain email or phone columns. Instead, identities are normalized across separate tables to support multiple login methods (OAuth, Passkeys, Magic Links) for a single account.

Table/Type	Description	Key Fields
User	Canonical account record.	id, privacyMode, insertedAt
UserIdentity	Linked authentication methods.	provider, uid, authProvider
UserToken	Session and verification secrets.	secret_hash, context, entropy_id
EmailAddress	Normalized unique email store.	address

Sources: ARCHITECTURE.md:164-185, mobile/schema.graphql:467-505

Social Graph

The Social domain implements a relationship-based visibility layer. It manages follow states and hard access restrictions (blocks) that override any content visibility rules.

Content and Media

Content is divided into durable posts and reusable media assets. Posts can be categorized as STANDARD or STORY types, with stories potentially carrying expiration metadata.

• Posts: Contain body text, author references, and links to media.
• Media Assets: Track the lifecycle of binary files from PENDING_UPLOAD to PROCESSED.

Sources: ARCHITECTURE.md:215-227, mobile/schema.graphql:386-435

Live Sessions and Chat

Live sessions represent transient events that transition through lifecycle states. Chat messages are decoupled from session management to handle high-throughput moderation and retention independently.

GraphQL API Core Types

The GraphQL schema provides the primary interface for mobile and web clients, implementing the following core nodes:

GraphQL Type	Purpose	Pagination Support
User	Represents the viewer or other accounts.	Yes (PostConnection)
Post	Represents shared content (standard/story).	Yes (PostConnection)
LiveSession	Represents active or recorded broadcasts.	Yes (LiveSessionConnection)
ChatMessage	Individual messages within a session.	Yes (ChatMessageConnection)
MediaAsset	Metadata for uploaded binaries.	No (Direct fetch/mutation)

Sources: mobile/schema.graphql:356-545

Database Conventions Summary

Technical requirements for the persistence layer as defined in system architecture and agent instructions:

// mobile/src/theme/tokens.ts - Client-side representations of data constraints
export const spacing = { xs: 4, sm: 8, md: 16, lg: 24, xl: 32 };
export const radius = { sm: 8, md: 14, lg: 24, pill: 999 };

Sources: mobile/src/theme/tokens.ts:4-15

• Entropy IDs: UUIDv7 identifiers are used for all public-facing IDs to prevent IDOR vulnerabilities while maintaining time-based sorting.
• Soft Deletion: Moderated content (e.g., chat messages) transitions to a REMOVED status rather than immediate hard deletion to preserve audit trails.
• Relational Integrity: Pure UUIDv7 identifiers are reserved for specific exceptions like user_tokens, while primary tables utilize bigint.

Sources: AGENTS.md:5-11, mobile/schema.graphql:442-445, ARCHITECTURE.md:68-75

Summary

The Core Schema and Data Model provide a rigid yet extensible framework for LiveCanvas. By separating ephemeral state from durable facts and enforcing domain boundaries at the schema level, the system ensures that social visibility, content delivery, and account security are handled by specialized logic layers. This model facilitates a "modular monolith" approach where subsystems like Live and Chat can eventually be scaled or extracted without impacting the core Accounts or Social visibility policies.

Sources: ARCHITECTURE.md:38-44, ARCHITECTURE.md:280-285