# Repository Guidelines

## Project Structure & Modules
- Gateway (`gateway/`): FastAPI entrypoint in `main.py`, routes under `api/` (`health.py`, `openai_speech.py`, `voices.py`), shared helpers in `core/`, voice registry in `voices/` and runtime port in `port.txt`.
- Worker (`worker/`): Queue consumer in `core/queue_worker.py`, XTTS2 synthesis in `engine/xtts2_loader.py`, audio export in `engine/audio_export.py`, voice assets in `voices/`.
- Tooling: `Makefile` drives Docker workflow, `docker-compose.yml` wires gateway/worker/redis, helper scripts in `scripts/` (`find_port.py`, `selftest.py`).

## Build, Test, and Run
- `make build` – build gateway + worker images.
- `make up` – start stack with auto port selection (writes `gateway/port.txt`).
- `make status` / `make logs` – check containers and follow logs.
- `make selftest` – end-to-end smoke test against the running stack (health + sample synthesis).
- Local debug (no Docker): install deps with `pip install -r gateway/requirements.gateway.txt` and `pip install -r worker/requirements.worker.txt`, then `python gateway/main.py` and `python worker/main.py`; start Redis via `docker run -p 6379:6379 redis:7`.

## Coding Style & Naming
- Python, prefer PEP8 with 4-space indents and snake_case names for modules, functions, and vars; keep route names aligned with OpenAI-compatible paths (`/v1/audio/speech`, `/v1/voices/register`).
- Keep modules small and focused (API logic in `gateway/api`, queue/Redis helpers in `core`).
- Favor explicit config via env vars (`REDIS_HOST`, `GATEWAY_PORT`); avoid hardcoded ports besides the 8000–8100 scan range.

## Testing Guidelines
- Primary check is the smoke test: run `make selftest` after changes that touch API, queue, or audio paths.
- For new logic, add lightweight unit tests (e.g., under `gateway/tests/` or `worker/tests/`) named `test_<feature>.py`; prefer pytest-style asserts.
- When adding audio or queue code, include sanity checks (e.g., validate `mime` and byte length) to avoid silent failures.

## Commit & Pull Request Practices
- Commits: short, imperative subjects (e.g., `add queue timeout guard`, `tune xtts export`). Group related changes; avoid mixing refactors with feature work.
- Pull Requests: describe intent, list test commands executed (e.g., `make selftest`), mention affected endpoints or worker behaviors, and link issues when available. Provide screenshots or audio sample paths only if UX or output format changes.

## Security & Operations Notes
- Do not commit voice assets beyond small samples; keep secrets out of the repo and prefer env vars or Docker secrets.
- Gateway listens on the selected local port only; expose externally via reverse proxy/HTTPS in production. Keep worker services internal and behind the queue.