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).

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.

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.

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.

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.

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.