21

master-docs/AGENT_MASTER_REFERENCE.md

@@ -0,0 +1,156 @@
+# Agent Master Reference — IGNY8
+
+Purpose: provide a single, navigable reference for any new agent (human or automated) to locate the exact files, entry points, and functional responsibilities across the IGNY8 monorepo. Use this as the starting point for feature work, bug fixes, or integrations.
+
+Contents
+- Repository snapshot (concise tree)
+- Key modules & responsibilities (table)
+- Important functions / entrypoints (table)
+- Quick agent workflow (5 steps)
+- Setup & common commands
+
+---
+
+**Repository Snapshot (Top-level, concise)**
+
+- `backend/` : Django project and related management scripts
+  - `manage.py` : Django CLI entry
+  - `requirements.txt` : Python deps
+  - `igny8_core/` : main Django package
+    - `settings.py`, `asgi.py`, `wsgi.py`, `celery.py`
+    - `api/`, `ai/`, `auth/`, `admin/`, `business/`, `modules/`, `utils/`
+  - `frontend/` (legacy frontend bundle inside backend)
+
+- `frontend/` : Vite + React application (modern front-end)
+  - `package.json`, `vite.config.ts`, `src/` (React + TS), `public/`
+
+- `master-docs/` : documentation; authoritative notes about architecture
+
+- `docker-compose.app.yml` : local dev stack (DB, cache, web, worker)
+
+---
+
+**Key Modules & Purpose**
+
+| Module / Path | Purpose / Responsibility | Quick Notes |
+|---|---|---|
+| `backend/manage.py` | Django management entrypoint | Run migrations, tests, server |
+| `igny8_core/settings.py` | Central config for Django | Env-driven; source of secrets/flags |
+| `igny8_core/celery.py` | Celery app configuration | Worker + beat scheduling setup |
+| `igny8_core/ai/` | AI orchestration layer | Models and engine integration |
+| `igny8_core/api/` | REST endpoints for backend | Look here for API implementations |
+| `frontend/` | Modern frontend app | `src/` contains components, hooks, services |
+| `docker-compose.app.yml` | Local dev orchestration | DB, cache, web, worker definitions |
+| `master-docs/` | Documentation and process| Use for architecture decisions and public docs |
+
+---
+
+**Important Files & Entrypoints (where to start for common tasks)**
+
+| Task | File / Function | Where to look |
+|---|---|---|
+| Start backend locally | `backend/manage.py` | `python manage.py runserver` (see file for settings) |
+| Celery worker/beat | `igny8_core/celery.py` | `celery -A igny8_core worker` and `celery -A igny8_core beat` |
+| Add/inspect REST endpoint | `igny8_core/api/` | Search for view classes or `@api_view` functions |
+| AI model orchestration | `igny8_core/ai/engine.py` (or `ai_core.py`) | See `05-AI-FRAMEWORK-IMPLEMENTATION.md` in `master-docs/` |
+| Frontend page/component | `frontend/src/pages/` and `frontend/src/components/` | Use the `App` and route files in `src/` |
+
+---
+
+**Function / Area Quick-Reference (examples)**
+
+- Celery and periodic tasks
+  - File: `igny8_core/celery.py`
+  - Purpose: configure Celery app, load periodic tasks (beat schedule is present at `backend/celerybeat-schedule`).
+
+- AI orchestration
+  - Files: `igny8_core/ai/ai_core.py`, `igny8_core/ai/engine.py` (or similarly named)
+  - Purpose: implement model selection, prompt orchestration, caching, and engine interfaces.
+
+- API handlers
+  - Path: `igny8_core/api/` (search for submodules per resource)
+  - Purpose: HTTP endpoints used by `frontend/` and external integrations.
+
+- Frontend data services
+  - Path: `frontend/src/services/` and `frontend/src/api/`
+  - Purpose: client-side API wrappers; coordinate expected backend response shapes.
+
+---
+
+**Agent Quick Workflow — 5 Steps**
+
+1. Identify the feature or bug area
+   - Use this reference to map the user-facing feature to `frontend/` pages and `igny8_core/api/` endpoints.
+   - Search for the route or identifiable component in `frontend/src/`.
+
+2. Locate the backend API handler
+   - From the frontend service or API call, open the corresponding URL and find the view in `igny8_core/api/`.
+   - Inspect serializer, view, and model (if present) in the same directory.
+
+3. Check configuration and environment
+   - Open `igny8_core/settings.py` to find related flags and env vars.
+   - For scheduled/background work, inspect `igny8_core/celery.py` and `backend/celerybeat-schedule`.
+
+4. Implement change and run local checks
+   - Backend: create/modify files under `igny8_core/` and run `python manage.py test` or `pytest` as configured.
+   - Frontend: modify `frontend/src/` and run `npm run dev` or `npm run build` for production checks.
+
+5. Update documentation & tests
+   - Add or update `master-docs/*` when making cross-cutting changes.
+   - Update the `API-COMPLETE-REFERENCE.md` if API shapes change.
+
+---
+
+**Common Commands (PowerShell-friendly)**
+
+Backend setup and run (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/beat (PowerShell):
+
+```
+cd backend
+.\.venv\Scripts\Activate.ps1
+celery -A igny8_core worker -l info
+celery -A igny8_core beat -l info
+```
+
+Frontend dev (Windows PowerShell):
+
+```
+cd frontend
+npm install
+npm run dev
+```
+
+Docker compose local stack:
+
+```
+docker-compose -f docker-compose.app.yml up --build
+```
+
+---
+
+**Guidance for new agents**
+
+- Always cross-check `master-docs/` entries when making architectural changes.
+- When changing an API, update `master-docs/API-COMPLETE-REFERENCE.md` and the frontend wrappers in `frontend/src/services/`.
+- For AI changes, refer to `master-docs/05-AI-FRAMEWORK-IMPLEMENTATION.md` before editing `igny8_core/ai/`.
+
+---
+
+If you want, I can:
+
+- Expand the file tree to include all files per directory (full tree).
+- Generate a CSV or JSON mapping of file → responsibilities for programmatic use.
+- Add an index of search terms and likely filenames for quick grep commands.
+
+End of reference.