Feed & Orchestration Context

Relevant source files

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

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

The Feed context serves as the primary read-side orchestrator within the LiveCanvas architecture. Unlike other core contexts that manage the lifecycle of specific entities (such as users or posts), the Feed context is responsible for composing data from across the system to populate client-facing surfaces. Its scope includes the home timeline, story reels, active live session listings, and content ranking or filtering based on complex visibility rules.

The Feed context does not own primary records; instead, it acts as a consumer of data produced by the Social, Content, and Live contexts. It ensures that the "Who is live" and "What is new" views are delivered efficiently to the GraphQL API while strictly adhering to relationship-based access controls.

Sources: ARCHITECTURE.md:144-150, ARCHITECTURE.md:213-219

Architectural Role and Composition

The Feed context follows a read-oriented design pattern. It performs cross-context orchestration to build a unified view for the user. It relies on the Social context to provide the policy layer for visibility (e.g., who can see what based on follow/block status) and the Content and Live contexts for the actual data payloads.

Orchestration Flow

The following diagram illustrates how the Feed context aggregates data from disparate domain boundaries to serve a client request:

The Feed context acts as a "Read-Side Orchestrator," ensuring that transient state (like active viewers) and durable state (like posts) are merged into a single API response.

Sources: ARCHITECTURE.md:144-150, ARCHITECTURE.md:213-219

API Surface and Data Structures

The Feed context is exposed primarily through the GraphQL API, adhering to Relay-first conventions including global IDs and cursor-based pagination (Connections and Edges).

Primary Feed Queries

The following table summarizes the key entry points for the Feed & Orchestration system defined in the GraphQL schema:

Query	Return Type	Description
homeFeed	PostConnection	Retrieves the primary timeline of posts for the viewer.
storyFeed	PostConnection	Orchestrates ephemeral or story-style content.
liveNow	LiveSessionConnection	Lists currently active live sessions accessible to the viewer.
replayFeed	LiveSessionConnection	Provides access to ended live sessions with recording metadata.

Sources: mobile/schema.graphql:7-12, AGENTS.md:11-12

Visibility and Filtering Logic

Feed orchestration is heavily dependent on the visibility rules established by the Social context. Content is filtered based on the following criteria:

• Public/Private Accounts: Content from private accounts is only included if a FOLLOWERS relationship exists and is ACCEPTED.
• Blocks/Mutes: The Social context provides blocks which override any follow-based access. The Feed must exclude content from blocked users.
• Lifecycle State: Live sessions are only orchestrated into the liveNow feed when their status is LIVE. Once finalized, they move to the replayFeed.

Sources: ARCHITECTURE.md:144-150, ARCHITECTURE.md:255-263, mobile/schema.graphql:275-279

Data Flow: Feed Retrieval

When a client requests a feed, the system must perform a sequence of checks to ensure the data is both relevant and authorized.

Technical Constraints and Conventions

The implementation of Feed & Orchestration must adhere to specific backend conventions to maintain performance and security:

• Pagination: All feed queries MUST use first/after or last/before parameters for cursor-based pagination.
• Authorization: Viewer authorization must be re-applied in GraphQL node fetchers and child field resolvers to prevent IDOR (CWE-639) when navigating from feed items to specific resource details.
• Timestamping: All timestamps used for ranking or filtering in the feed must use :utc_datetime_usec.
• Durable State: The Feed relies on PostgreSQL as the system of record for all items being orchestrated.

Sources: AGENTS.md:5-15, ARCHITECTURE.md:54-60

Summary

The Feed & Orchestration context is a vital modular monolith boundary that handles the complexity of data aggregation. By separating the read-side orchestration from the primary write-side contexts (like Content or Live), the system maintains strict internal boundaries while providing a high-performance, Relay-compliant API for mobile and web clients. Its primary responsibility is the secure and efficient delivery of the home timeline, stories, and live session surfaces through a unified GraphQL interface.