Skip to main content

Contributor Patterns

This repo is large enough that contributors need repeatable extension patterns, not just file searches.

Add a New API Endpoint​

  1. Update or create the relevant domain router.
  2. Use the shared auth and DB dependency aliases.
  3. Inject domain services through dependency aliases, not direct construction.
  4. Register the router in the app router wiring.

Add a New Domain​

Follow the canonical shape:

models.py
repository.py
service.py
schemas.py
types.py
exceptions.py
dependencies.py
router.py

tasks/ is the reference implementation for the full pattern.

Add a New Database Table​

  1. Define the ORM model using the shared base.
  2. Use UUID foreign keys consistently.
  3. Create an Alembic revision.
  4. Review the migration before applying it.

Add a New Socket.IO Handler​

  1. Create a handler class in realtime/handlers/.
  2. Register the command in the command enum/schema layer.
  3. Wire it into the handler factory.

Add a New Cron Job​

  1. Create the job implementation in workers/cron/jobs/.
  2. Register the schedule/spec in the cron job registry.

Repo Rules Worth Remembering​

  • Use uv run for Python commands.
  • Run Ruff only on changed Python files before calling work complete.
  • Use dependency aliases instead of bare Depends(...) in route signatures.
  • Do not bypass the billing reservation path for billable work.
  • Treat root docs and codemaps as aids, but prefer current code and env examples when they disagree.

Verification Commands​

uv run pytest
uv run ruff check path/to/changed.py
uv run ruff format --check path/to/changed.py
curl http://localhost:8000/health