basaHoushanApi/.github/copilot-instructions.md

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 mounts routes from src/routes and models from src/models. DB uses Tortoise ORM configured in src/settings.py and 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.

• Environment & config:

  • Environment variables live in .api.env (referenced by Settings.model_config in 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/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 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.