mirror of
https://github.com/ClaperCo/Claper.git
synced 2026-05-18 13:16:18 +02:00
feat: add AGENTS.md for repository guidance and development practices
This commit is contained in:
Alex Lion
176
AGENTS.md
Normal file
176
AGENTS.md
Normal file
@@ -0,0 +1,176 @@
|
||||
# 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
|
||||
|
||||
```bash
|
||||
./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
|
||||
|
||||
```bash
|
||||
./with_env.sh mix phx.server
|
||||
./with_env.sh iex -S mix phx.server
|
||||
```
|
||||
|
||||
### Testing and Quality
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
./with_env.sh mix gettext.extract
|
||||
./with_env.sh mix gettext.merge priv/gettext
|
||||
```
|
||||
|
||||
### Assets and Production Build
|
||||
|
||||
```bash
|
||||
./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.
|
||||
112
CLAUDE.md
112
CLAUDE.md
@@ -1,112 +0,0 @@
|
||||
# CLAUDE.md
|
||||
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||
|
||||
## Common Development Commands
|
||||
|
||||
### Setup and Dependencies
|
||||
```bash
|
||||
# Install dependencies
|
||||
mix deps.get
|
||||
mix setup # Runs deps.get + ecto.setup
|
||||
|
||||
# Setup database
|
||||
mix ecto.setup # Creates DB, runs migrations, seeds
|
||||
mix ecto.reset # Drops DB and runs ecto.setup
|
||||
|
||||
# Install frontend dependencies
|
||||
cd assets && npm install && cd ..
|
||||
```
|
||||
|
||||
### Running the Application
|
||||
```bash
|
||||
# Start Phoenix server
|
||||
mix phx.server
|
||||
|
||||
# Or inside IEx
|
||||
iex -S mix phx.server
|
||||
```
|
||||
|
||||
### Testing
|
||||
```bash
|
||||
# Run tests
|
||||
mix test
|
||||
|
||||
# Run specific test file
|
||||
mix test test/path/to/test_file.exs
|
||||
|
||||
# Run test with specific line number
|
||||
mix test test/path/to/test_file.exs:42
|
||||
```
|
||||
|
||||
### Code Quality
|
||||
```bash
|
||||
# Format code
|
||||
mix format
|
||||
|
||||
# Run Credo for code analysis
|
||||
mix credo
|
||||
```
|
||||
|
||||
### Building Assets
|
||||
```bash
|
||||
# For production deployment
|
||||
mix assets.deploy
|
||||
```
|
||||
|
||||
## High-Level Architecture
|
||||
|
||||
Claper is an interactive presentation platform built with Phoenix Framework and Elixir. It enables real-time audience interaction during presentations through polls, forms, messages, and quizzes.
|
||||
|
||||
### Core Components
|
||||
|
||||
1. **Phoenix LiveView Architecture**
|
||||
- Real-time updates without JavaScript through WebSocket connections
|
||||
- LiveView modules in `lib/claper_web/live/` handle interactive UI
|
||||
- Presence tracking for real-time user counts
|
||||
|
||||
2. **Main Domain Contexts** (in `lib/claper/`)
|
||||
- `Accounts` - User management, authentication, OIDC integration
|
||||
- `Events` - Core presentation/event management
|
||||
- `Posts` - Audience messages and reactions
|
||||
- `Polls` - Interactive polls with real-time voting
|
||||
- `Forms` - Custom forms for audience feedback
|
||||
- `Quizzes` - Quiz functionality with LTI support
|
||||
- `Presentations` - Slide management and state tracking
|
||||
- `Embeds` - External content embedding
|
||||
|
||||
3. **Authentication & Authorization**
|
||||
- Multiple auth methods: email/password, OIDC
|
||||
- Role-based access control with admin panel
|
||||
- LTI 1.3 support for educational platforms
|
||||
|
||||
4. **Real-time Features**
|
||||
- Phoenix PubSub for broadcasting updates
|
||||
- Phoenix Presence for tracking online users
|
||||
- LiveView for reactive UI without custom JavaScript
|
||||
|
||||
5. **Background Jobs**
|
||||
- Oban for background job processing
|
||||
- Email sending
|
||||
|
||||
6. **Frontend Stack**
|
||||
- Tailwind CSS for styling (with DaisyUI components)
|
||||
- Alpine.js for minimal JavaScript interactions
|
||||
- esbuild for JavaScript bundling
|
||||
- Separate admin and user interfaces
|
||||
|
||||
7. **Key LiveView Modules**
|
||||
- `EventLive.Show` - Attendee view
|
||||
- `EventLive.Presenter` - Presenter control view
|
||||
- `EventLive.Manage` - Event management interface
|
||||
- `AdminLive.*` - Admin panel components
|
||||
|
||||
8. **Database Structure**
|
||||
- PostgreSQL with Ecto
|
||||
- Key models: User, Event, Post, Poll, Quiz, PresentationState
|
||||
- Soft deletes for users
|
||||
- UUID-based public identifiers
|
||||
|
||||
9. **LTI Integration**
|
||||
- LTI 1.3 support for quizzes, publish score to LMS
|
||||
- LTI launch handling in `LtiController`
|
||||
Reference in New Issue
Block a user