98 lines
5.6 KiB
Markdown
98 lines
5.6 KiB
Markdown
<!-- Copilot / AI agent instructions for the IGNY8 monorepo (backend + frontend) -->
|
|
# 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
|