# Repository Guidelines

## Project Structure & Module Organization
- `main.py` boots FastAPI, wiring caching, translation, and routing layers.
- Core domain lives in `app/`: `api/routes/` for HTTP endpoints, `services/` for OpenAI translation and allergen detection, `core/` for caching and exceptions, and `utils/` for shared helpers.
- Settings and logging load from `config/config.yaml` via `app/config/settings.py`; container assets (`Dockerfile`, `docker-compose.yml`, `deploy.sh`) and runtime logs (`logs/`) sit at the repo root.

## Build, Test, and Development Commands
- `python -m venv .venv && source .venv/bin/activate` creates an isolated interpreter for local work.
- `pip install -r requirements.txt` installs API, OpenAI, and Redis dependencies.
- `uvicorn main:app --reload --port 8000` serves the API locally with hot reload for route and settings changes.
- `docker-compose up --build` runs the stack with Redis and rebuilds containers when code or dependencies change.
- `pytest` executes the suite; pair with `-k` or `-vv` when triaging regressions.

## Coding Style & Naming Conventions
- Target Python 3.11, enforce 4-space indentation, and follow PEP 8 naming (`snake_case` functions, `PascalCase` classes, uppercase constants).
- Add type hints and concise docstrings when behavior is not self-evident; prefer `dataclass` or pydantic models for structured payloads.
- Reuse `get_logger()` from `app/config/logging_config.py` to keep JSON logs consistent instead of ad-hoc `print`.

## Testing Guidelines
- Use `pytest` with async clients (`httpx.AsyncClient`) when exercising FastAPI routes inside the lifespan context.
- Organize tests under `tests/api/` for endpoint flows and `tests/services/` for translation or caching units; mirror module names for clarity.
- Cover edge cases such as cache expiry, `allergensOnly` filters, and translation fallbacks before merging.

## Commit & Pull Request Guidelines
- Write short, Title Case commit subjects (e.g., `Debug & Logs`, `Improve Translation Cache`) under 72 characters; expand in the body if configs or migrations shift.
- PRs should state motivation, linked issues, test evidence (`pytest`, manual curl), and call out updates to `config/config.yaml` or deployment scripts.
- Include sample request/response payloads or screenshots when API contracts or logging formats change to aid reviewers.

## Configuration & Security
- Never commit `.env` secrets; rely on settings defaults and document overrides in PRs.
- Update `config/config.yaml` in tandem with `app/config/settings.py` so environments stay in sync.
- Keep `logs/` for local debugging only; scrub sensitive data before sharing artifacts.