# 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