diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 00000000..41146735 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,97 @@ + +# IGNY8 — Copilot Instructions + +Purpose: quickly orient AI coding agents so they can make safe, high-value changes across the IGNY8 monorepo. + +Key facts (big picture) +- **Monorepo layout:** Backend (Django) lives under `backend/` and the core Python package is `igny8_core/`. Frontend is in `frontend/` (Vite + React/TS). Documentation and architecture notes live in `master-docs/` and repo root `README.md`. +- **Services & runtime:** The project uses Django with Celery (see `igny8_core/celery.py` and `backend/celerybeat-schedule`), and a modern frontend build in `frontend/`. There is a `docker-compose.app.yml` to bring up combined services for development. +- **APIs:** Backend exposes REST endpoints under its `api/` modules and integrates with the WordPress bridge (see `WORDPRESS-PLUGIN-INTEGRATION.md` in `master-docs/`). AI components live under `igny8_core/ai/`. + +Where to look first +- `backend/manage.py` — Django project CLI and common quick tests. +- `igny8_core/settings.py` — central configuration; check how secrets and environment variables are read before altering settings. +- `igny8_core/celery.py` and `backend/celerybeat-schedule` — Celery setup, periodic tasks, and beat schedule. +- `backend/requirements.txt` — Python dependencies; use it when creating or updating virtualenvs. +- `docker-compose.app.yml` — local dev composition (DB, cache, web, worker); follow it for local integration testing. +- `frontend/package.json`, `vite.config.ts` — frontend scripts and dev server commands. +- `master-docs/` — architecture and process documents (use these before making cross-cutting changes). + +Project-specific conventions and patterns +- Python package: main Django app is `igny8_core` — add new reusable modules under `igny8_core/*` and keep app boundaries clear (`ai/`, `api/`, `auth/`, `modules/`). +- Settings & secrets: inspect `igny8_core/settings.py` for environment-based config; prefer adding new env vars there rather than hard-coding secrets. +- Celery tasks live near the domain logic; follow established naming and task registration patterns in `igny8_core/celery.py`. +- Frontend: components live under `frontend/src/` grouped by feature; tests use `vitest` (see `vitest.config.ts`). +- Docs-first: many architectural decisions are documented — prefer updating `master-docs/*` when you change interfaces, APIs, or long-lived behavior. + +Integration points & external dependencies +- Database and cache: check `docker-compose.app.yml` for configured DB and cache services used in local dev (use same service names when writing connection logic). +- Celery & broker: Celery is configured in `igny8_core/celery.py`; ensure worker-related changes are tested with `celery -A igny8_core worker` and `celery -A igny8_core beat` when applicable. +- AI modules: `igny8_core/ai/` contains AI engine integration points — review `ai_core.py` and `engine.py` before changing model orchestration logic. +- Frontend ↔ Backend: frontend calls backend REST APIs; update API shapes in `api/` and coordinate with `frontend/src/api/`. + +Developer workflows (copyable commands) +- Create a Python virtualenv and run backend locally: +```powershell +cd backend +python -m venv .venv +.\.venv\Scripts\Activate.ps1 +pip install -r requirements.txt +python manage.py migrate +python manage.py runserver +``` +- Run Celery worker (in a separate shell): +```powershell +cd backend +.\.venv\Scripts\Activate.ps1 +celery -A igny8_core worker -l info +celery -A igny8_core beat -l info +``` +- Run the app stack via Docker Compose (local integration): +```powershell +docker-compose -f docker-compose.app.yml up --build +``` +- Frontend dev server: +```powershell +cd frontend +npm install +npm run dev +``` +- Run backend tests (Django or pytest as configured): +```powershell +cd backend +.\.venv\Scripts\Activate.ps1 +python manage.py test +# or `pytest` if pytest is configured +``` + +Rules for safe automated changes +- Preserve API contracts: when changing backend API responses, update `frontend/` calls and `master-docs/API-COMPLETE-REFERENCE.md`. +- Keep settings/environment changes explicit: add new env vars to `settings.py` and document them in `master-docs/`. +- When adding scheduled work, register tasks via Celery and update any existing beat schedules (and document in `master-docs/`). +- Avoid breaking the frontend build: run `npm run build` or `npm run dev` locally after API changes that affect the client. + +Search hacks / quick finds +- Find API surface: search `api/` and `igny8_core/api/` for endpoint implementations. +- Find AI orchestration: search `igny8_core/ai/` for `engine.py` and `ai_core.py` references. +- Find Celery tasks: grep for `@shared_task` or `@app.task` in `igny8_core/`. + +Testing and safety +- Use the repo `requirements.txt` and virtualenv for backend testing; run `python manage.py test` or `pytest` depending on existing test setup. +- For frontend, run `npm run test` or `vitest` as configured in `vitest.config.ts`. +- For integration changes, run the `docker-compose.app.yml` stack and exercise both web and worker services. + +When you are unsure +- Read `master-docs/02-APPLICATION-ARCHITECTURE.md` and `04-BACKEND-IMPLEMENTATION.md` before large changes. +- Open an issue and link to `master-docs/` when proposing cross-cutting changes (database, schema, API contract). + +Examples & quick references +- Start backend: `backend/manage.py runserver` +- Celery entrypoint: `igny8_core/celery.py` +- Local stack: `docker-compose.app.yml` +- Frontend dev: `frontend/package.json` & `vite.config.ts` + +Next steps for humans +- Tell me which parts you want expanded: API reference, CI/CD snippets, deployment docs, or example tickets to implement. + +— End