Claper/AGENTS.md

AGENTS.md

This file provides repository guidance for coding agents working in this project, regardless of vendor or runtime.

Purpose

Claper is an interactive presentation platform built with Elixir, Phoenix, and LiveView. It supports real-time audience interaction through polls, forms, posts, quizzes, and presentation controls.

Use this document as the canonical agent guide for repository context, workflows, and implementation constraints.

Working Principles

• Read the relevant existing files before editing them.
• Match existing naming, structure, and conventions instead of introducing new patterns.
• Keep changes targeted and incremental.
• Prefer thin web layers and place business logic in contexts.
• Do not hardcode secrets, credentials, or environment-specific values.
• When changing behavior, add or update tests in the affected area when practical.
• Run the smallest relevant verification steps before finishing.

Common Commands

Prefer running mix commands through ./with_env.sh so values from .env are loaded in the shell environment. Use plain mix ... only when the task does not depend on repository environment variables.

When running tests, make sure the loaded .env sets MIX_ENV=test before invoking ./with_env.sh mix test. Do not run tests against a shell environment configured for dev or prod.

Setup and Dependencies

./with_env.sh mix deps.get
./with_env.sh mix setup
./with_env.sh mix ecto.setup
./with_env.sh mix ecto.reset
cd assets && npm install && cd ..

Running the Application

./with_env.sh mix phx.server
./with_env.sh iex -S mix phx.server

Testing and Quality

# Ensure `.env` contains `MIX_ENV=test` before running test commands
./with_env.sh mix test
./with_env.sh mix test test/path/to/test_file.exs
./with_env.sh mix test test/path/to/test_file.exs:42
./with_env.sh mix format
./with_env.sh mix credo

Localization

./with_env.sh mix gettext.extract
./with_env.sh mix gettext.merge priv/gettext

Assets and Production Build

./with_env.sh mix assets.deploy

Architecture Overview

Core Stack

• Phoenix + LiveView for real-time UI
• PostgreSQL + Ecto for persistence
• Oban for background jobs
• Tailwind CSS + DaisyUI for styling
• Alpine.js for lightweight client-side interactions
• esbuild for frontend bundling

Main Contexts

• Accounts for users, auth, roles, and OIDC
• Events for presentation and event management
• Posts for audience messages and reactions
• Polls for voting flows
• Forms for feedback forms
• Quizzes for quiz flows and LTI integration
• Presentations for slide and state management
• Embeds for external content embedding

Main Web Areas

• lib/claper_web/live/event_live/show* for attendee-facing interactions
• lib/claper_web/live/event_live/presenter* for presenter controls
• lib/claper_web/live/event_live/manage* for event management
• lib/claper_web/live/admin_live/ for admin interfaces

Real-Time Patterns

• Use Phoenix PubSub for event broadcasts
• Use Phoenix Presence for online user tracking
• Event-scoped topics commonly follow "event:#{event.uuid}"

Project Conventions

Elixir and Phoenix

• Context modules live in lib/claper/
• Schemas typically live in lib/claper/<context>/
• Use Claper.Repo and Ecto queries instead of raw SQL
• Keep LiveViews thin and move reusable business logic into contexts
• Common LiveView callbacks include mount/3, handle_params/3, handle_event/3, and handle_info/2
• Use assign/2 and assign_new/2 for LiveView state management
• Every new user-facing text must be localized with Gettext instead of hardcoded strings
• After adding or changing translatable strings, run ./with_env.sh mix gettext.extract and ./with_env.sh mix gettext.merge priv/gettext

Database

• Migrations live in priv/repo/migrations/
• Public identifiers commonly use UUIDs
• Schemas use Claper.Schema as the base when appropriate
• Set on_delete behavior explicitly for foreign keys in migrations
• Prefer reversible migrations when possible
• Avoid destructive migrations without a backfill or rollout plan

Frontend

• Follow existing Tailwind and DaisyUI usage
• Prefer LiveView interactions over custom JavaScript when possible
• Use Alpine.js only where lightweight client-side behavior is justified

Auth and Access Control

• Check ownership or role before any mutation
• Route-level auth belongs in plugs under lib/claper_web/plugs/
• LiveView auth should use existing on_mount patterns
• Be alert for IDOR risks when loading resources from params

Testing Guidance

• Context tests usually live in test/claper/
• Web and LiveView tests usually live in test/claper_web/
• Use Claper.DataCase for context tests
• Use ClaperWeb.ConnCase for controller and web tests
• Match existing fixtures and helpers from test/support/
• Cover happy paths, validation failures, and authorization boundaries
• For PubSub and LiveView features, verify relevant events and UI updates

Security and Safety Checks

Before finishing sensitive changes, review for:

• SQL injection risks from interpolated queries
• XSS risks from unsafe rendering of user content
• Missing authorization checks on mutations and admin flows
• IDOR risks from unscoped resource lookups
• Secret leakage in code, logs, or assigns
• Unsafe command execution with user input
• PubSub topics that expose cross-event data

Operations and Deployment

• Runtime configuration should come from environment variables, especially in config/runtime.exs
• Keep Docker and CI changes minimal, cache-friendly, and explicit
• Ensure production releases still support migrations through lib/claper/release.ex
• Update .env.sample when introducing required environment variables
• Ensure assets are built for production changes that require them

Change Strategy

When implementing work:

1. Understand the request and inspect the affected code paths.
2. Identify the smallest coherent change that fits existing architecture.
3. Implement with minimal surface area.
4. Run relevant checks such as mix format, mix test, or mix credo.
5. Note any remaining risks, skipped checks, or follow-up work.