## Quick Agent Instructions for Houshan API

This repository is a FastAPI service with Tortoise ORM (Aerich) migrations, several AI integrations, and Docker-based developer workflows. Use these notes to be productive quickly.

- **Big picture**: API server in [src/main.py](src/main.py) mounts routes from `src/routes` and models from `src/models`. DB uses Tortoise ORM configured in [src/settings.py](src/settings.py) and [src/config.py](src/config.py). Background jobs use APScheduler (timezone Asia/Tehran). Key AI integrations include Fal (`FAL_KEY`), Suno (`SUNO_API_KEY`), OpenAI/Anthropic, and Chroma (see `requirements.txt`).

- **Run / dev workflows**:
  - Local (fast): run with Uvicorn: `uvicorn src.main:app --reload --host 0.0.0.0 --port 8000` (requires env from `.api.env`).
  - Docker: use the Makefile targets which wrap `docker compose`:
    - `make up` — build & start services
    - `make logs` — follow logs
    - `make shell-app` — open a shell inside the `app` container
  - `docker-compose.yml` uses env file `.api.env` and exposes the API on port 8000 inside the container. See [docker-compose.yml](docker-compose.yml).

- **Environment & config**:
  - Environment variables live in `.api.env` (referenced by `Settings.model_config` in [src/config.py](src/config.py)). Always copy production secrets out of commits; `serviceAccountKey.json` is present and sensitive.
  - DB URL lives in `DATABASE_URL` and is referenced from `src/settings.py` and `pyproject.toml` via Aerich config.

- **Migrations**:
  - Aerich is configured in `pyproject.toml` (`tool.aerich.tortoise_orm = "settings.TORTOISE_ORM"`). Typical commands (run with proper `DATABASE_URL` in env):
    - `aerich init -t src.settings.TORTOISE_ORM`
    - `aerich migrate --name "describe"`
    - `aerich upgrade`
  - Migrations live under `migrations/models`.

- **Code layout & conventions**:
  - `src/routes` – routers are registered centrally by `register_routers(app)` in [src/main.py](src/main.py).
  - `src/services` – contains pluggable service modules (storage, tool, chatbot, etc.). Prefer calling service functions rather than re-implementing integrations.
  - `src/tasks` – background jobs and scheduled tasks (scheduled from `src/main.py` via APScheduler).
  - Use async/await consistently; many IO layers (httpx, aioboto3, asyncpg, tortoise) are async-first.

- **Integration tips & patterns (project-specific)**:
  - Fal video generation: endpoint implemented in [src/main.py](src/main.py) under `/public/generate-video`. It expects `FAL_KEY` and uses `FAL_BASE_URL`. Keep the key in `.api.env`.
  - Suno: there is a webhook `/suno/callback` that writes to `SunoTask` (see `src/main.py`). When testing webhooks locally, route requests to the container or use `ngrok`.
  - Storage: `src/services/storage.py` abstracts file storage (S3/compatible). Use it for large files instead of returning raw streams.
  - Database model lookups use `await Model.get_or_none(...)` — follow that idiom to avoid exceptions.

- **Testing & debugging**:
  - No automated test harness found. Use `uvicorn` locally or `make up` + `make logs` for smoke tests.
  - For DB schema issues, run `aerich migrate`/`upgrade` and inspect `migrations/models`.
  - To inspect runtime logs or DB state in containers: `make logs` and `make shell-app`.

- **Where to change things (examples)**:
  - Add a new API router: create file in `src/routes`, export a `router`, and ensure `register_routers` imports it.
  - Add a scheduled job: add function in `src/tasks/*` and register it in `src/main.py` with `scheduler.add_job(..., CronTrigger(..., timezone=tehran_tz))`.

- **Caveats & gotchas**:
  - The project is async-first; avoid blocking calls (do CPU-heavy work in separate workers).
  - Several keys and external services (Fal, Suno, Chroma, Google, MailerSend) are used—stub or mock them when necessary.
  - Aerich migrations may be sensitive to `TORTOISE_ORM` path; keep `pyproject.toml` and `src/settings.py` in sync.

If any section is unclear or you'd like more examples (e.g., how to add a route or run aerich locally on Windows), tell me which part to expand.