weirsoe-party-protocol/AGENTS.md

Repository Guidelines

Project Structure & Module Organization

partyhub/ is the Django project entrypoint (settings.py, urls.py, asgi.py). Backend apps live at the repo root: lobby/ handles session and player flows, fupogfakta/ owns game rules and scoring, realtime/ holds websocket/broadcast code, and core_admin/ plus voice/ cover admin and future audio integration. Shared locale data lives in shared/i18n/, helper scripts in scripts/, deployment assets in infra/, and release or smoke evidence in docs/.

Frontend code is split in two layers: frontend/src/ contains the framework-agnostic TypeScript API client and SPA state helpers, while frontend/angular/src/ contains the Angular 19 shell for host and player screens.

Build, Test, and Development Commands

Install backend dependencies with .venv/bin/pip install -r requirements.txt.

• .venv/bin/python manage.py runserver starts the Django dev server.
• .venv/bin/python manage.py migrate applies schema changes.
• .venv/bin/python manage.py check runs Django configuration checks.
• .venv/bin/python manage.py test lobby runs the backend suite currently enforced in CI.
• npm --prefix frontend test runs Vitest for the shared TypeScript client.
• npm --prefix frontend run build performs the TypeScript compile check.
• npm --prefix frontend/angular start serves the Angular shell locally.
• npm --prefix frontend/angular test runs Angular-side Vitest smoke tests.
• .venv/bin/python scripts/check_i18n_drift.py validates shared locale keys.

Coding Style & Naming Conventions

Use 4-space indentation in Python and follow Django conventions: snake_case for functions, PascalCase for models, explicit on_delete on ForeignKeys, and committed migrations in each app’s migrations/ package. Keep business rules server-authoritative.

Use 2-space indentation in TypeScript and Angular. Match the existing style: single quotes, semicolons, PascalCase classes, camelCase functions, and kebab-case filenames such as gameplay-phase-machine.ts. Keep API types in frontend/src/api/types.ts aligned with backend JSON payloads.

Testing Guidelines

Backend tests live in <app>/tests.py; frontend tests live in frontend/tests/*.test.ts and frontend/angular/src/**/*.spec.ts. No numeric coverage gate is committed, so add targeted tests for every gameplay, i18n, or payload-contract change. Before opening a PR, run manage.py check, manage.py test lobby, and npm --prefix frontend/angular test at minimum.

Commit & Pull Request Guidelines

Recent history follows short, imperative subjects with optional scopes, for example fix(gameplay): ..., test(lobby): ..., and chore: .... Keep commits small and reference issue numbers when relevant. Open PRs from feature/<name> branches with a clear problem statement, linked issue, test evidence, and screenshots for host/player UI changes. If you touch USE_SPA_UI, staging flow, or i18n artifacts, include the related smoke or parity document in docs/.