Agent Workflows & Development Guidelines

Relevant source files

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

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

This document outlines the operational protocols and architectural standards for AI agents and human developers contributing to the LiveCanvas backend. The primary focus for the current development phase (V1) is achieving product feature completeness, specifically across the Accounts, Social, Live, Chat, and Feed domains.

The system is designed as a modular monolith using Elixir and Phoenix, emphasizing strict internal boundaries, GraphQL for primary client interactions, and PostgreSQL as the sole persistent data store. Developers must adhere to specific batching policies and coordination workflows to ensure stability and parallel progress across backend and mobile lanes.
Sources: ARCHITECTURE.md:12-25, ARCHITECTURE.md:43-50, AGENTS.md:52-54

Core Backend Conventions

Developers must follow standardized patterns to ensure consistency across the Elixir application. This includes specific data types, security protocols, and API structures.

Data and Security Standards

• Timestamps: Use :utc_datetime_usec for all timestamp fields to maintain microsecond precision.
• Primary Keys: Relational tables default to bigint primary keys accompanied by an :entropy_id (UUIDv7 generated by Postgres). Exceptions like user_tokens may use pure UUIDv7 identifiers.
• Hashing: Use SHA3-based token hashing for persisted secrets; SHA-2 is explicitly avoided.
• Type Safety: Public functions must include typespecs, and developers are required to run mix typecheck when modifying typed code.
  Sources: AGENTS.md:3-10

API and Connectivity

The backend uses a Relay-first GraphQL API. All node fetchers and child field resolvers must re-apply viewer authorization to prevent IDOR (Insecure Direct Object Reference) vulnerabilities, even when using globally refetchable IDs.
Sources: AGENTS.md:11-13

Agent Planning & Coordination

Workflows are managed through a tiered planning system designed to allow parallel execution without write-scope conflicts.

The Coordination Dashboard

The docs/plans/NOW.md file serves as the coordinator dashboard. For specific lane work, developers use lane-specific pointers:

• Backend: docs/plans/backend/NOW.md
• Mobile: docs/plans/mobile/NOW.md

Batching and Execution Policy

Agents are encouraged to execute meaningful batches (one full task section or 3-5 related steps) rather than single micro-steps. Verification must be performed for each batch using the minimum necessary commands.

Rule	Description
Commit Boundary	Commit at milestones (completed section, visible change, or checkpoint).
Verification	Run mix compile after boundary changes to surface violations.
Parallelization	Dispatch subagents only for 2+ independent tracks; each needs a unique worktree.
Status Updates	Keep checkboxes updated; do not create docs-only commits.
Sources: AGENTS.md:16-41, ARCHITECTURE.md:88-91

Architectural Boundaries

LiveCanvas enforces a modular monolith structure using the boundary library. Each context module acts as an interface boundary that must be respected.

Primary Contexts

1. Accounts: Manages user state, authentication, and identity linking.
2. Social: Owns relationship logic (follows, blocks, mutes) and visibility policies.
3. Live: Orchestrates session lifecycles and media-facing states.
4. Content: Stores durable user content like posts and media metadata.
5. Feed: A read-oriented layer for retrieving timelines and "who is live" surfaces.
   Sources: ARCHITECTURE.md:104-145

Development Environment & Tooling

The frontend and asset pipelines are integrated into the Phoenix application, utilizing Tailwind CSS and DaisyUI for styling.

Asset Management

• Styling: Tailwind CSS is configured via @plugin directives in app.css. It incorporates custom DaisyUI themes (light/dark) and Heroicons.
• LiveView: The application uses Phoenix LiveView, with assets managed via assets/js/app.js.
• Development Tools: In development mode, the phx:live_reload:attached event enables server log streaming to the browser console and allows developers to jump to HEEx component definitions by clicking elements while holding "c" or "d".
  Sources: assets/css/app.css:1-50, assets/js/app.js:35-65

GraphQL Schema Implementation

The mobile client interacts with the backend using the defined GraphQL schema, which includes nodes, connections, and mutations for all V1 features.

Feature Group	Key Mutations
Auth	signUp, logIn, refreshAuthTokens, beginAuthChallenge
Social	followUser, blockUser, muteUser, acceptFollowRequest
Live	startLiveSession, joinLiveSession, endLiveSession
Content	createPost, requestMediaUpload, deletePost
Sources: mobile/schema.graphql:30-70

Conclusion

The development of LiveCanvas is governed by strict modular boundaries and a coordination-first workflow for agents. By prioritizing durable state in PostgreSQL and ephemeral state in OTP, while adhering to the documented batching and commit policies, the project maintains high velocity toward its V1 product goals without sacrificing architectural integrity.