# 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 `ForeignKey`s, 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/`.