igny8/master-docs/AGENT_MASTER_REFERENCE.md

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.