# IGNY8 Documentation - Master Index

**Last Updated:** December 9, 2024  
**Purpose:** Single source of truth - Find any file, function, or feature in 1-2 steps

---

## 🎯 Quick Find - Start Here

### I want to...

| Task | Go To | File Location Reference |
|------|-------|------------------------|
| **Add a new feature** | Find module below → Open reference doc | See "Code Locations" in each doc |
| **Fix a bug** | Find workflow → See exact function | Function names listed (no code) |
| **Understand data flow** | [40-WORKFLOWS/](#workflows) | Visual diagrams included |
| **Find an API endpoint** | [20-API/](#api-endpoints) | Endpoint + handler location |
| **Modify UI component** | [30-FRONTEND/](#frontend) | Component path + props |
| **Change database model** | [10-BACKEND/MODELS.md](#backend) | Model + fields + file path |
| **Deploy or configure** | [50-DEPLOYMENT/](#deployment) | Environment setup |

---

## 📚 Documentation Structure

### 00-SYSTEM - System Architecture
**Purpose:** High-level design, tech stack, core concepts

| File | What's Inside | When to Read |
|------|---------------|--------------|
| [ARCHITECTURE-OVERVIEW.md](00-SYSTEM/ARCHITECTURE-OVERVIEW.md) | System design, microservices, architecture patterns | Understanding overall system |
| [TECH-STACK.md](00-SYSTEM/TECH-STACK.md) | All technologies: Django, React, PostgreSQL, Redis, Celery | Technology decisions |
| [MULTITENANCY.md](00-SYSTEM/MULTITENANCY.md) | Account isolation, tenant context, middleware | Multi-tenant features |
| [AUTHENTICATION.md](00-SYSTEM/AUTHENTICATION.md) | JWT tokens, sessions, permissions, roles | Auth/authz changes |
| [DATA-FLOWS.md](00-SYSTEM/DATA-FLOWS.md) | Cross-system workflows with diagrams | Understanding flows |

---

### 10-BACKEND - Backend Services & Models
**Purpose:** All backend code locations, models, services, business logic

#### Core Backend Files

| File | What's Inside | When to Read |
|------|---------------|--------------|
| [OVERVIEW.md](10-BACKEND/OVERVIEW.md) | Backend architecture, module structure | Understanding backend organization |
| [MODELS.md](10-BACKEND/MODELS.md) | All database models with fields (no code) | Database schema reference |
| [SERVICES.md](10-BACKEND/SERVICES.md) | Business logic services and their purposes | Service layer understanding |

#### Module-Specific References

| Module | File | What's Inside |
|--------|------|---------------|
| **Accounts** | [accounts/ACCOUNTS-REFERENCE.md](10-BACKEND/accounts/ACCOUNTS-REFERENCE.md) | User, Account, Role models + auth endpoints<br>📁 `backend/igny8_core/auth/` |
| **Billing** | [billing/BILLING-REFERENCE.md](10-BACKEND/billing/BILLING-REFERENCE.md) | Plans, Subscriptions, Invoices, Payments<br>📁 `backend/igny8_core/business/billing/` |
| **Billing** | [billing/CREDITS-SYSTEM.md](10-BACKEND/billing/CREDITS-SYSTEM.md) | Credit allocation, deduction, transactions<br>📁 `services/credit_service.py` |
| **Billing** | [billing/PAYMENT-METHODS.md](10-BACKEND/billing/PAYMENT-METHODS.md) | Payment method config, manual approvals<br>📁 `models.py` + `admin.py` |
| **Planner** | [planner/PLANNER-REFERENCE.md](10-BACKEND/planner/PLANNER-REFERENCE.md) | Keywords → Clusters → Ideas pipeline<br>📁 `backend/igny8_core/business/planning/` |
| **Planner** | [planner/KEYWORD-CLUSTERING.md](10-BACKEND/planner/KEYWORD-CLUSTERING.md) | Clustering algorithm, similarity scoring<br>📁 `services/keyword_service.py` |
| **Planner** | [planner/IDEA-GENERATION.md](10-BACKEND/planner/IDEA-GENERATION.md) | AI-powered idea generation from clusters<br>📁 `services/idea_service.py` |
| **Writer** | [writer/WRITER-REFERENCE.md](10-BACKEND/writer/WRITER-REFERENCE.md) | Content, Tasks, Publishing models<br>📁 `backend/igny8_core/business/content/` |
| **Writer** | [writer/CONTENT-GENERATION.md](10-BACKEND/writer/CONTENT-GENERATION.md) | AI content creation flow, prompts<br>📁 `services/content_generation_service.py` |
| **Writer** | [writer/IMAGES-SYSTEM.md](10-BACKEND/writer/IMAGES-SYSTEM.md) | Image generation, storage, management<br>📁 `services/image_service.py` |
| **Writer** | [writer/PUBLISHING.md](10-BACKEND/writer/PUBLISHING.md) | Review workflow, status transitions<br>📁 `views.py` + `serializers.py` |
| **Automation** | [automation/AUTOMATION-REFERENCE.md](10-BACKEND/automation/AUTOMATION-REFERENCE.md) | Full automation pipeline overview<br>📁 `backend/igny8_core/business/automation/` |
| **Automation** | [automation/PIPELINE-STAGES.md](10-BACKEND/automation/PIPELINE-STAGES.md) | Stage-by-stage breakdown with functions<br>📁 `services/automation_service.py` |
| **Automation** | [automation/SCHEDULER.md](10-BACKEND/automation/SCHEDULER.md) | Celery tasks, scheduling, background jobs<br>📁 `tasks.py` |
| **Integrations** | [integrations/WORDPRESS-INTEGRATION.md](10-BACKEND/integrations/WORDPRESS-INTEGRATION.md) | WordPress sync, publishing, webhooks<br>📁 `backend/igny8_core/business/integration/` |
| **Integrations** | [integrations/AI-SERVICES.md](10-BACKEND/integrations/AI-SERVICES.md) | OpenAI, Anthropic API integration<br>📁 `backend/igny8_core/ai/` |
| **Integrations** | [integrations/IMAGE-GENERATION.md](10-BACKEND/integrations/IMAGE-GENERATION.md) | DALL-E, Stability AI integration<br>📁 `services/image_generation.py` |
| **Sites** | [sites/SITES-REFERENCE.md](10-BACKEND/sites/SITES-REFERENCE.md) | Site, Sector, Industry models<br>📁 `backend/igny8_core/auth/models.py` |

---

### 20-API - REST API Endpoints
**Purpose:** All API endpoints with request/response formats and handler locations

| File | What's Inside | When to Read |
|------|---------------|--------------|
| [API-REFERENCE.md](20-API/API-REFERENCE.md) | Complete endpoint list with methods | API overview |
| [AUTHENTICATION-ENDPOINTS.md](20-API/AUTHENTICATION-ENDPOINTS.md) | Login, register, tokens, refresh<br>📁 `auth/views.py` + `auth/urls.py` | Auth API changes |
| [PLANNER-ENDPOINTS.md](20-API/PLANNER-ENDPOINTS.md) | Keywords, clusters, ideas CRUD<br>📁 `modules/planner/views.py` | Planner API |
| [WRITER-ENDPOINTS.md](20-API/WRITER-ENDPOINTS.md) | Content, tasks, images CRUD<br>📁 `modules/writer/views.py` | Writer API |
| [AUTOMATION-ENDPOINTS.md](20-API/AUTOMATION-ENDPOINTS.md) | Start/stop automation, status<br>📁 `modules/automation/views.py` | Automation API |
| [BILLING-ENDPOINTS.md](20-API/BILLING-ENDPOINTS.md) | Invoices, payments, credits<br>📁 `business/billing/views.py` | Billing API |
| [INTEGRATION-ENDPOINTS.md](20-API/INTEGRATION-ENDPOINTS.md) | WordPress, external services<br>📁 `modules/integration/views.py` | Integration API |

---

### 30-FRONTEND - React UI Components & State
**Purpose:** Frontend architecture, components, state management, pages

| File | What's Inside | When to Read |
|------|---------------|--------------|
| [FRONTEND-ARCHITECTURE.md](30-FRONTEND/FRONTEND-ARCHITECTURE.md) | React structure, routing, file organization | Frontend overview |
| [STATE-MANAGEMENT.md](30-FRONTEND/STATE-MANAGEMENT.md) | Zustand stores, state flow<br>📁 `frontend/src/store/` | State changes |
| [COMPONENTS.md](30-FRONTEND/COMPONENTS.md) | Reusable UI components library<br>📁 `frontend/src/components/` | Component usage |

#### Module UI References

| Module | File | What's Inside |
|--------|------|---------------|
| **Planner** | [planner/PLANNER-UI.md](30-FRONTEND/planner/PLANNER-UI.md) | Keywords, clusters, ideas pages<br>📁 `frontend/src/pages/planner/` |
| **Writer** | [writer/WRITER-UI.md](30-FRONTEND/writer/WRITER-UI.md) | Content, tasks, publishing UI<br>📁 `frontend/src/pages/writer/` |
| **Automation** | [automation/AUTOMATION-UI.md](30-FRONTEND/automation/AUTOMATION-UI.md) | Automation dashboard, controls<br>📁 `frontend/src/pages/automation/` |
| **Billing** | [billing/BILLING-UI.md](30-FRONTEND/billing/BILLING-UI.md) | Plans, payments, invoices UI<br>📁 `frontend/src/pages/billing/` |

---

### 40-WORKFLOWS - Complete User Journeys
**Purpose:** End-to-end workflows with visual diagrams (no code)

| File | What's Inside | When to Read |
|------|---------------|--------------|
| [SIGNUP-TO-ACTIVE.md](40-WORKFLOWS/SIGNUP-TO-ACTIVE.md) | User signup → Payment → Account activation | Onboarding flow |
| [CONTENT-LIFECYCLE.md](40-WORKFLOWS/CONTENT-LIFECYCLE.md) | Keyword → Cluster → Idea → Task → Content → Published | Content creation |
| [PAYMENT-WORKFLOW.md](40-WORKFLOWS/PAYMENT-WORKFLOW.md) | User payment → Admin approval → Credit allocation | Payment processing |
| [AUTOMATION-WORKFLOW.md](40-WORKFLOWS/AUTOMATION-WORKFLOW.md) | Full automation run with all stages | Automation understanding |
| [WORDPRESS-SYNC.md](40-WORKFLOWS/WORDPRESS-SYNC.md) | Bidirectional sync between IGNY8 ↔ WordPress | WP integration |

---

### 50-DEPLOYMENT - Environment & Deployment
**Purpose:** Setup, deployment, configuration guides

| File | What's Inside | When to Read |
|------|---------------|--------------|
| [ENVIRONMENT-SETUP.md](50-DEPLOYMENT/ENVIRONMENT-SETUP.md) | Local, staging, production setup | Environment config |
| [DOCKER-DEPLOYMENT.md](50-DEPLOYMENT/DOCKER-DEPLOYMENT.md) | Container setup, docker-compose | Container deployment |
| [DATABASE-MIGRATIONS.md](50-DEPLOYMENT/DATABASE-MIGRATIONS.md) | Migration strategy, commands | Schema changes |

---

### 90-ARCHIVED - Historical Reference
**Purpose:** Old documentation kept for reference (deprecated)

Archived files from previous documentation iterations.

---

## 🔍 Search Strategies

### By Feature

| Feature | Start Here | Then Read |
|---------|-----------|-----------|
| User Signup | [40-WORKFLOWS/SIGNUP-TO-ACTIVE.md](40-WORKFLOWS/SIGNUP-TO-ACTIVE.md) | [10-BACKEND/accounts/](10-BACKEND/accounts/) |
| Content Generation | [40-WORKFLOWS/CONTENT-LIFECYCLE.md](40-WORKFLOWS/CONTENT-LIFECYCLE.md) | [10-BACKEND/writer/CONTENT-GENERATION.md](10-BACKEND/writer/CONTENT-GENERATION.md) |
| Payment Processing | [40-WORKFLOWS/PAYMENT-WORKFLOW.md](40-WORKFLOWS/PAYMENT-WORKFLOW.md) | [10-BACKEND/billing/](10-BACKEND/billing/) |
| WordPress Publishing | [40-WORKFLOWS/WORDPRESS-SYNC.md](40-WORKFLOWS/WORDPRESS-SYNC.md) | [10-BACKEND/integrations/WORDPRESS-INTEGRATION.md](10-BACKEND/integrations/WORDPRESS-INTEGRATION.md) |
| Automation Run | [40-WORKFLOWS/AUTOMATION-WORKFLOW.md](40-WORKFLOWS/AUTOMATION-WORKFLOW.md) | [10-BACKEND/automation/](10-BACKEND/automation/) |

### By Technology

| Technology | Where Used | Documentation |
|-----------|------------|---------------|
| Django REST Framework | Backend API | [20-API/](20-API/) |
| React 19 | Frontend UI | [30-FRONTEND/](30-FRONTEND/) |
| Zustand | State Management | [30-FRONTEND/STATE-MANAGEMENT.md](30-FRONTEND/STATE-MANAGEMENT.md) |
| PostgreSQL | Database | [10-BACKEND/MODELS.md](10-BACKEND/MODELS.md) |
| Celery | Background Tasks | [10-BACKEND/automation/SCHEDULER.md](10-BACKEND/automation/SCHEDULER.md) |
| JWT | Authentication | [00-SYSTEM/AUTHENTICATION.md](00-SYSTEM/AUTHENTICATION.md) |
| OpenAI | AI Content | [10-BACKEND/integrations/AI-SERVICES.md](10-BACKEND/integrations/AI-SERVICES.md) |

### By Code Location

| Directory | Documentation |
|-----------|---------------|
| `backend/igny8_core/auth/` | [10-BACKEND/accounts/](10-BACKEND/accounts/) |
| `backend/igny8_core/business/billing/` | [10-BACKEND/billing/](10-BACKEND/billing/) |
| `backend/igny8_core/business/planning/` | [10-BACKEND/planner/](10-BACKEND/planner/) |
| `backend/igny8_core/business/content/` | [10-BACKEND/writer/](10-BACKEND/writer/) |
| `backend/igny8_core/business/automation/` | [10-BACKEND/automation/](10-BACKEND/automation/) |
| `backend/igny8_core/business/integration/` | [10-BACKEND/integrations/](10-BACKEND/integrations/) |
| `frontend/src/pages/` | [30-FRONTEND/](30-FRONTEND/) |
| `frontend/src/store/` | [30-FRONTEND/STATE-MANAGEMENT.md](30-FRONTEND/STATE-MANAGEMENT.md) |
| `frontend/src/components/` | [30-FRONTEND/COMPONENTS.md](30-FRONTEND/COMPONENTS.md) |

---

## 📖 Documentation Standards

### Every doc file includes:

1. **Purpose Statement** - What this document covers
2. **File Locations** - Exact paths to code files (no code shown)
3. **Function/Class Names** - What to look for in files
4. **Related Docs** - Cross-references to other documentation
5. **Data Flows** - Visual workflows (ASCII diagrams allowed)

### What's NOT in docs:

❌ Code snippets  
❌ Implementation details  
❌ Line-by-line walkthroughs  

### What IS in docs:

✅ File paths: `backend/igny8_core/business/billing/services/credit_service.py`  
✅ Function names: `CreditService.add_credits(account, amount, type, description)`  
✅ Model fields: `account.credits`, `invoice.total`, `payment.status`  
✅ Endpoints: `POST /v1/billing/admin/payments/confirm/`  
✅ Workflows: ASCII diagrams, state tables, field mappings  

---

## 🎓 Example Usage

### Scenario 1: "I want to add a new payment method"

1. **Start:** Check [Quick Find](#quick-find---start-here) table
2. **Navigate to:** [10-BACKEND/billing/PAYMENT-METHODS.md](10-BACKEND/billing/PAYMENT-METHODS.md)
3. **Find:** 
   - Model: `PaymentMethodConfig`
   - File: `backend/igny8_core/business/billing/models.py`
   - Admin: `PaymentMethodConfigAdmin` in `admin.py`
4. **Read:** Field descriptions, validation rules
5. **Modify:** Open exact files, add new payment method

### Scenario 2: "Content generation is broken"

1. **Start:** [40-WORKFLOWS/CONTENT-LIFECYCLE.md](40-WORKFLOWS/CONTENT-LIFECYCLE.md)
2. **Follow:** Visual flow diagram
3. **Identify:** Which stage is failing
4. **Navigate to:** [10-BACKEND/writer/CONTENT-GENERATION.md](10-BACKEND/writer/CONTENT-GENERATION.md)
5. **Find:** 
   - Service: `ContentGenerationService`
   - File: `backend/igny8_core/business/content/services/content_generation_service.py`
   - Function: `generate_content(task_id)`
6. **Debug:** Open exact file, check function

### Scenario 3: "How do I add a new API endpoint?"

1. **Start:** [20-API/API-REFERENCE.md](20-API/API-REFERENCE.md)
2. **Find:** Similar endpoint pattern
3. **Navigate to:** Module-specific endpoint doc (e.g., [20-API/PLANNER-ENDPOINTS.md](20-API/PLANNER-ENDPOINTS.md))
4. **Learn:** 
   - ViewSet location
   - Serializer pattern
   - URL routing
5. **Implement:** Follow exact same structure

---

## 🔄 Keeping Docs Updated

### When to update:

- ✅ New feature added → Update relevant module doc
- ✅ API changed → Update endpoint doc
- ✅ Workflow modified → Update workflow doc
- ✅ Model field added → Update MODELS.md

### Update checklist:

1. Update module reference doc (e.g., PLANNER-REFERENCE.md)
2. Update API doc if endpoint changed
3. Update workflow doc if flow changed
4. Update CHANGELOG.md with change summary
5. Do NOT add code to docs - only file paths and function names

---

## 📞 Need Help?

### Finding the right doc:

1. **Feature-based:** Start with [40-WORKFLOWS/](#workflows)
2. **Module-based:** Start with [10-BACKEND/](#backend) or [30-FRONTEND/](#frontend)
3. **API-based:** Start with [20-API/](#api-endpoints)
4. **Setup-based:** Start with [50-DEPLOYMENT/](#deployment)

### Still can't find it?

Check [CHANGELOG.md](CHANGELOG.md) for recent changes that might point you to the right doc.

---

**Last Updated:** December 9, 2024  
**Maintained By:** Development Team  
**Format:** Markdown with no code snippets