# Repository Guidelines

## Project Structure & Module Organization
- `app/` FastAPI service code: `main.py` app factory, `engines/` TTS backends (Piper, Kokoro, XTTS, F5, StyleTTS, ChatTTS), `utils/` helpers (text chunking, audio concat, cache keys), `models/` default model assets.
- `app/asset/` runtime assets and audio cache (overridable via `AUDIO_CACHE_DIR`); `asset/` holds Docker/runtime assets mounted into the container.
- `tests/` pytest suite with async API coverage and fixtures that redirect cache paths.
- `docs/` reference material; `scripts/` helper scripts (health checks, setup); `Dockerfile`, `docker-compose*.yml`, and `Makefile` drive builds and orchestration.

## Build, Test, and Development Commands
- `make dev-up` Build from local source and start the stack; auto-picks a free host port.
- `make up` Run using the latest registry image; `make down` stops Compose services; `make logs` tails the app container.
- `make test` Run pytest with coverage over `app/` and `tests/`; honors `.venv` if present.
- Local uvicorn run (outside Docker): `uvicorn app.main:app --reload --host 0.0.0.0 --port 8000`.

## Coding Style & Naming Conventions
- Python code should follow PEP 8 with 4-space indentation and explicit type hints where meaningful; keep functions small and async-aware for I/O.
- Prefer FastAPI dependency injection patterns and pydantic models for request/response validation.
- Tests, fixtures, and helpers use `test_*.py` naming; keep fixtures in `tests/conftest.py`.
- Configuration lives in `app/config.py` via pydantic settings; read values from `.env` instead of hardcoding.

## Testing Guidelines
- Use `pytest`/`pytest-asyncio`; mark async tests with `@pytest.mark.asyncio`.
- Ensure Piper models required by tests exist under `app/models/piper/` (see README instructions) or skip conditionally as in existing tests.
- When adding engines, supply health checks (`healthcheck`), model/voice listing, and synthesis tests mirroring `tests/test_api.py`.
- Keep coverage broad on `/tts`, `/engines`, `/models`, `/health`, and error paths (invalid engine/model/speaker).

## Commit & Pull Request Guidelines
- Follow the existing conventional prefix style (`feat:`, `fix:`, `docs:`, etc.) as seen in git history.
- Commits should be scoped and descriptive; avoid bundling unrelated changes.
- PRs should include: purpose and behavior summary, key test commands run (e.g., `make test`), notes on model/config prerequisites, and screenshots/log snippets only when behavior is user-visible.

## Security & Configuration Tips
- Copy `.env.example` to `.env` and avoid committing secrets or model paths tied to personal systems.
- Validate engine activation lists via `ACTIVE_ENGINES` and ensure cache directories (`AUDIO_CACHE_DIR`) are writable before running locally or in containers.
- Large model files live outside the image; mount them via Compose volumes and confirm licenses (e.g., XTTS `XTTS_ACCEPT_LICENSE`).