32 lines
2.7 KiB
Markdown
32 lines
2.7 KiB
Markdown
# 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.
|