Skip to content

AGENTS.md

Latest commit

 

History

History
102 lines (75 loc) · 3.69 KB

AGENTS.md

File metadata and controls

102 lines (75 loc) · 3.69 KB

AGENTS.md

This file guides automated agents and contributors working in this repository. It mirrors CLAUDE.md and reflects current codebase practices.

Project Overview

PingPong is an educational AI assistant platform with:

  • Backend: FastAPI (Python 3.11+), async SQLAlchemy, Pydantic v2
  • Frontend: SvelteKit with TypeScript
    • web/pingpong (Svelte 4, Tailwind v3, Flowbite-Svelte)
  • Authorization: OpenFGA
  • Authentication: JWT (magic links, SAML/SSO)
  • LMS: Canvas LTI 1.3
  • DB: Postgres (prod) or SQLite (dev/tests)

Repo Layout

  • pingpong/ FastAPI app, models, schemas, authz, integrations
  • alembic/ database migrations
  • web/pingpong/ main SvelteKit UI (Svelte 4)
  • scripts/ one-off scripts and CLI helpers
  • config.toml, test_config.toml configuration defaults/tests

Common Development Commands

Backend (repo root)

uv sync
CONFIG_PATH=config.local.toml uv run fastapi dev pingpong --port 8000 --host 0.0.0.0 --reload
uv run pytest
uv run alembic revision --autogenerate -m "description of change"
uv run python -m pingpong db migrate

Frontend: main app (web/pingpong)

pnpm install
pnpm dev
pnpm check
pnpm lint
pnpm format
pnpm test

Docker

./start-dev-docker.sh

Backend Architecture and Patterns

  • Request middleware order: session parsing -> authz session -> DB session -> logging. Access request.state["db"], request.state["authz"], request.state["session"].
  • Authorization uses composable expressions in pingpong/permission.py (Authz, LoggedIn, InstitutionAdmin) and OpenFGA model in pingpong/authz/authz.fga.json.
  • Database is async SQLAlchemy; use config.db.driver.async_session() or @db_session_handler for non-request tasks.
  • Schemas live in pingpong/schemas.py (Pydantic v2). Return schemas directly from endpoints.
  • Central config is pingpong/config.py via BaseSettings and TOML (CONFIG_PATH=config.local.toml).

Frontend Architecture and Patterns

web/pingpong (Svelte 4)

  • API client lives in web/pingpong/src/lib/api.ts. Use expandResponse/explodeResponse helpers and streaming utilities in src/lib/streams.ts.
  • State is managed with Svelte stores; conversation state uses ThreadManager in src/lib/stores/thread.ts.
  • UI uses Tailwind and Flowbite-Svelte components, plus custom components in src/lib/components.

Code Style and Conventions

Python

  • Follow existing async-first patterns and type hints.
  • Keep imports grouped: stdlib, third-party, local.
  • Use logging via logging.getLogger(__name__) and raise HTTPException for HTTP errors.
  • Prefer Pydantic models for request/response shapes instead of raw dicts.

Svelte/TypeScript

web/pingpong:

  • Prettier config uses 2 spaces, single quotes, no trailing commas, print width 100.
  • ESLint with @typescript-eslint and eslint-plugin-svelte.

Adding New API Endpoints

  1. Add route handlers in pingpong/server.py alongside related endpoints.
  2. Add/extend Pydantic schemas in pingpong/schemas.py.
  3. Apply permission expressions via Depends(Authz(...)).
  4. Implement client call in web/pingpong/src/lib/api.ts.
  5. Add tests under pingpong/test_*.py using fixtures in conftest.py and helpers in pingpong/testutil.py.

Database Migrations

  1. Update models in pingpong/models.py.
  2. Generate migration: uv run alembic revision --autogenerate -m "description".
  3. Review migration in alembic/versions/.
  4. Apply: uv run python -m pingpong db migrate.

Development Notes

  • Tests load test_config.toml automatically (conftest.py sets CONFIG_PATH).
  • Dev email uses the mock sender; check API console output for magic links.
  • LTI flows use sessionStorage for iframe-safe session tokens in the main UI.