282 lines
15 KiB
Markdown
282 lines
15 KiB
Markdown
# 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
|