igny8/.github/copilot-instructions.md

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:

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):

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):

docker-compose -f docker-compose.app.yml up --build

• Frontend dev server:

cd frontend
npm install
npm run dev

• Run backend tests (Django or pytest as configured):

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