53 lines
4.1 KiB
Markdown
53 lines
4.1 KiB
Markdown
## 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.
|