# IGNY8 System Master Reference

**Version:** 1.0.0  
**Last Updated:** November 24, 2025  
**Purpose:** Complete system architecture and navigation reference for the IGNY8 SaaS platform and WordPress integration plugin.

---

## Table of Contents

1. [System Overview](#system-overview)
2. [Architecture](#architecture)
3. [Backend Deep Dive](#backend-deep-dive)
4. [Frontend Deep Dive](#frontend-deep-dive)
5. [WordPress Plugin Deep Dive](#wordpress-plugin-deep-dive)
6. [Integration Architecture](#integration-architecture)
7. [AI Framework](#ai-framework)
8. [Data Models](#data-models)
9. [API Reference](#api-reference)
10. [Workflows](#workflows)
11. [Developer Navigation Map](#developer-navigation-map)
12. [Troubleshooting Map](#troubleshooting-map)

---

## System Overview

IGNY8 is a full-stack AI-powered SEO content management platform consisting of three main components:

1. **IGNY8 SaaS Application** - Multi-tenant Django + React application
2. **WordPress Bridge Plugin** - Bidirectional sync between WordPress and IGNY8
3. **Sites Renderer** - Public-facing site deployment system

### Core Capabilities

| Capability | Implementation | Status |
|------------|----------------|--------|
| **Multi-Tenancy** | Account → Site → Sector hierarchy | ✅ Live |
| **Keyword Management** | Planner module (Keywords, Clusters, Ideas) | ✅ Live |
| **AI Content Generation** | Writer module with OpenAI integration | ✅ Live |
| **Image Generation** | AI-powered via DALL-E and Runware | ✅ Live |
| **WordPress Publishing** | Bidirectional sync via REST API | ✅ Live |
| **Internal Linking** | Linker module for SEO optimization | ✅ Live |
| **Content Optimization** | Optimizer module for scoring | ✅ Live |
| **Site Blueprints** | Site Builder for site structure | ✅ Live |
| **Automation** | Scheduled tasks and rules | ✅ Live |
| **Credit System** | Usage-based billing | ✅ Live |

---

## Architecture

### High-Level System Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                         User Layer                               │
├─────────────────────────────────────────────────────────────────┤
│  React Frontend (app.igny8.com)  │  WordPress Site (client)     │
│  - Vite 6.1.0 + React 19         │  - WP Bridge Plugin          │
│  - Zustand State Management      │  - REST API Endpoints        │
│  - React Router v7               │  - Bidirectional Sync        │
└─────────────────────┬───────────────────────────┬───────────────┘
                      │                           │
                      ▼                           ▼
┌─────────────────────────────────────────────────────────────────┐
│                    API Gateway (Django)                          │
├─────────────────────────────────────────────────────────────────┤
│  - JWT Authentication                                            │
│  - Unified Response Format (success, data, message, request_id) │
│  - Rate Limiting & Throttling                                    │
│  - Account Context Middleware                                    │
└─────────────────────┬───────────────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Business Logic Layer                          │
├─────────────────────────────────────────────────────────────────┤
│  Modules (ViewSets)          │  Business Logic (Services)        │
│  ─────────────────────────── │  ────────────────────────────     │
│  • Planner                   │  • Planning Services             │
│  • Writer                    │  • Content Services              │
│  • Linker                    │  • Linking Services              │
│  • Optimizer                 │  • Optimization Services         │
│  • Publisher                 │  • Publishing Services           │
│  • Site Builder              │  • Site Building Services        │
│  • Automation                │  • Automation Services           │
│  • Integration               │  • Integration Services          │
│  • System                    │  • System Settings               │
│  • Billing                   │  • Credit Services               │
└─────────────────────┬───────────────────┬───────────────────────┘
                      │                   │
                      ▼                   ▼
┌──────────────────────────────┐  ┌──────────────────────────────┐
│    AI Framework (Celery)      │  │   Database (PostgreSQL)       │
├──────────────────────────────┤  ├──────────────────────────────┤
│  • AIEngine                   │  │  • Account Isolation          │
│  • AICore                     │  │  • Site/Sector Scoping        │
│  • AI Functions Registry      │  │  • Relational Models          │
│  • Progress Tracking          │  │  • JSON Fields for Config     │
│  • Cost Tracking              │  │  • Indexed Queries            │
└──────────────────────────────┘  └──────────────────────────────┘
```

### Data Hierarchy

```
Account (Tenant)
├── Users (with roles)
├── Plan & Subscription
├── Credit Balance
└── Sites (1-N based on plan)
    ├── Industry (optional)
    ├── WordPress Integration (SiteIntegration)
    └── Sectors (1-5 per site)
        ├── Keywords
        ├── Clusters
        ├── Content Ideas
        ├── Tasks
        ├── Content
        └── Images
```

---

## Backend Deep Dive

### Technology Stack

- **Framework:** Django 5.2+
- **API:** Django REST Framework (DRF) with drf-spectacular
- **Database:** PostgreSQL
- **Task Queue:** Celery 5.3+ with Redis broker
- **Authentication:** JWT (PyJWT 2.8+)
- **AI:** OpenAI API, Runware API

### Project Structure

```
backend/
├── igny8_core/                     # Django project root
│   ├── settings.py                 # Django configuration
│   ├── urls.py                     # Root URL routing
│   ├── celery.py                   # Celery configuration
│   ├── wsgi.py                     # WSGI entry point
│   ├── asgi.py                     # ASGI entry point (future)
│   │
│   ├── auth/                       # Multi-tenancy & authentication
│   │   ├── models.py               # Account, User, Plan, Site, Sector
│   │   ├── views.py                # Auth ViewSets
│   │   ├── serializers.py          # Auth serializers
│   │   ├── middleware.py           # AccountContextMiddleware
│   │   └── urls.py                 # /api/v1/auth/ routes
│   │
│   ├── modules/                    # Feature modules (ViewSets)
│   │   ├── planner/                # Keywords, Clusters, Ideas
│   │   │   ├── views.py            # KeywordViewSet, ClusterViewSet, ContentIdeasViewSet
│   │   │   ├── serializers.py      # Serializers
│   │   │   ├── urls.py             # /api/v1/planner/ routes
│   │   │   └── apps.py             # App config
│   │   │
│   │   ├── writer/                 # Tasks, Content, Images
│   │   │   ├── views.py            # TasksViewSet, ContentViewSet, ImagesViewSet
│   │   │   ├── serializers.py      # Serializers
│   │   │   └── urls.py             # /api/v1/writer/ routes
│   │   │
│   │   ├── linker/                 # Internal linking
│   │   │   ├── views.py            # LinkerViewSet
│   │   │   └── urls.py             # /api/v1/linker/ routes
│   │   │
│   │   ├── optimizer/              # Content optimization
│   │   │   ├── views.py            # OptimizerViewSet
│   │   │   └── urls.py             # /api/v1/optimizer/ routes
│   │   │
│   │   ├── publisher/              # Publishing & deployment
│   │   │   ├── views.py            # PublisherViewSet, PublishingRecordViewSet
│   │   │   └── urls.py             # /api/v1/publisher/ routes
│   │   │
│   │   ├── site_builder/           # Site blueprints & pages
│   │   │   ├── views.py            # SiteBlueprintViewSet, PageBlueprintViewSet
│   │   │   ├── serializers.py      # Serializers
│   │   │   └── urls.py             # /api/v1/site-builder/ routes
│   │   │
│   │   ├── automation/             # Automation rules & tasks
│   │   │   ├── views.py            # AutomationRuleViewSet, ScheduledTaskViewSet
│   │   │   └── urls.py             # /api/v1/automation/ routes
│   │   │
│   │   ├── integration/            # External platform integrations
│   │   │   ├── views.py            # IntegrationViewSet
│   │   │   └── urls.py             # /api/v1/integration/ routes
│   │   │
│   │   ├── system/                 # Settings, prompts, integrations
│   │   │   ├── models.py           # AIPrompt, IntegrationSettings, AuthorProfile
│   │   │   ├── views.py            # AIPromptViewSet, AuthorProfileViewSet
│   │   │   ├── settings_views.py   # SystemSettingsViewSet
│   │   │   └── urls.py             # /api/v1/system/ routes
│   │   │
│   │   └── billing/                # Credits & transactions
│   │       ├── views.py            # CreditBalanceViewSet, CreditTransactionViewSet
│   │       ├── services.py         # CreditService
│   │       └── urls.py             # /api/v1/billing/ routes
│   │
│   ├── business/                   # Business logic & models
│   │   ├── planning/               # Planner models
│   │   │   └── models.py           # Keywords, Clusters, ContentIdeas
│   │   ├── content/                # Writer models
│   │   │   └── models.py           # Tasks, Content, Images
│   │   ├── linking/                # Linker services
│   │   ├── optimization/           # Optimizer services
│   │   ├── publishing/             # Publisher models
│   │   ├── site_building/          # Site builder models
│   │   ├── automation/             # Automation models
│   │   ├── integration/            # Integration models
│   │   │   ├── models.py           # SiteIntegration
│   │   │   └── services/           # IntegrationService, SyncService
│   │   └── billing/                # Billing models
│   │
│   ├── ai/                         # AI Framework
│   │   ├── engine.py               # AIEngine - Central orchestrator
│   │   ├── ai_core.py              # AICore - API calls & model selection
│   │   ├── base.py                 # BaseAIFunction - Function interface
│   │   ├── registry.py             # AI function registry
│   │   ├── prompts.py              # PromptRegistry
│   │   ├── tracker.py              # Progress & cost tracking
│   │   ├── tasks.py                # run_ai_task Celery wrapper
│   │   ├── settings.py             # Model configuration
│   │   ├── validators.py           # Validation functions
│   │   ├── constants.py            # AI constants
│   │   └── functions/              # AI function implementations
│   │       ├── auto_cluster.py     # Keyword clustering
│   │       ├── generate_ideas.py   # Content idea generation
│   │       ├── generate_content.py # Blog post generation
│   │       ├── generate_image_prompts.py  # Image prompt extraction
│   │       └── generate_images.py  # Image generation (DALL-E/Runware)
│   │
│   ├── api/                        # API base classes
│   │   ├── base.py                 # AccountModelViewSet, SiteSectorModelViewSet
│   │   ├── response.py             # success_response, error_response
│   │   ├── pagination.py           # CustomPageNumberPagination
│   │   ├── permissions.py          # Custom permissions
│   │   ├── throttles.py            # Rate limiting
│   │   └── exception_handlers.py   # Unified error handling
│   │
│   ├── middleware/                 # Custom middleware
│   │   ├── request_id.py           # RequestIDMiddleware
│   │   ├── resource_tracker.py     # ResourceTrackingMiddleware
│   │   └── __init__.py
│   │
│   ├── utils/                      # Shared utilities
│   │   ├── wordpress.py            # WordPress helpers
│   │   ├── content_normalizer.py   # Content processing
│   │   ├── queue_manager.py        # Queue utilities
│   │   └── ai_processor.py         # Legacy AI utilities
│   │
│   └── admin/                      # Django admin customization
│       ├── base.py                 # BaseAdmin
│       └── site.py                 # Admin site configuration
│
├── manage.py                       # Django management CLI
├── requirements.txt                # Python dependencies
└── Dockerfile                      # Docker configuration
```

### Core Base Classes

#### AccountModelViewSet
**Location:** `igny8_core/api/base.py`

Automatic account filtering for all resources. Used by modules that don't need site/sector filtering.

```python
class AccountModelViewSet(ModelViewSet):
    """Filters queryset by request.account automatically"""
    
    def get_queryset(self):
        return super().get_queryset().filter(account=self.request.account)
```

**Used by:** System, Billing, Auth modules

#### SiteSectorModelViewSet
**Location:** `igny8_core/api/base.py`

Automatic filtering by account, site, and sector. Used by content-related modules.

```python
class SiteSectorModelViewSet(ModelViewSet):
    """Filters by account, site, and sector from query params"""
    
    def get_queryset(self):
        queryset = super().get_queryset()
        site_id = self.request.query_params.get('site_id')
        sector_id = self.request.query_params.get('sector_id')
        # ... filtering logic
```

**Used by:** Planner, Writer, Site Builder, Publisher, Automation, Integration modules

### Middleware Stack

1. **RequestIDMiddleware** - Assigns unique ID to each request
2. **AccountContextMiddleware** - Sets `request.account` from JWT token
3. **ResourceTrackingMiddleware** - Tracks API usage metrics

---

## Frontend Deep Dive

### Technology Stack

- **Framework:** React 19.0.0
- **Build Tool:** Vite 6.1.0
- **Routing:** React Router v7.9.5
- **State:** Zustand 5.0.8
- **Styling:** Tailwind CSS 4.0.8
- **Charts:** ApexCharts 4.1.0
- **Icons:** Heroicons 2.2.0

### Project Structure

```
frontend/
├── src/
│   ├── main.tsx                    # Application entry point
│   ├── App.tsx                     # Main app with routing
│   ├── index.css                   # Global styles
│   │
│   ├── api/                        # API client layer
│   │   ├── client.ts               # Axios instance with interceptors
│   │   ├── auth.ts                 # Auth API calls
│   │   ├── planner.ts              # Planner API calls
│   │   ├── writer.ts               # Writer API calls
│   │   └── [module].ts             # Other module APIs
│   │
│   ├── store/                      # Zustand state management
│   │   ├── authStore.ts            # Auth state (user, tokens)
│   │   ├── siteStore.ts            # Site context
│   │   ├── moduleStore.ts          # Module-specific state
│   │   └── globalStore.ts          # Global app state
│   │
│   ├── pages/                      # Page components
│   │   ├── AuthPages/
│   │   │   ├── SignIn.tsx
│   │   │   └── SignUp.tsx
│   │   ├── Dashboard/
│   │   │   └── Home.tsx
│   │   ├── Planner/
│   │   │   ├── Dashboard.tsx
│   │   │   ├── Keywords.tsx
│   │   │   ├── Clusters.tsx
│   │   │   └── Ideas.tsx
│   │   ├── Writer/
│   │   │   ├── Dashboard.tsx
│   │   │   ├── Tasks.tsx
│   │   │   ├── Content.tsx
│   │   │   ├── ContentView.tsx
│   │   │   ├── Drafts.tsx
│   │   │   ├── Images.tsx
│   │   │   └── Published.tsx
│   │   ├── Linker/
│   │   │   ├── Dashboard.tsx
│   │   │   └── ContentList.tsx
│   │   ├── Optimizer/
│   │   │   ├── Dashboard.tsx
│   │   │   ├── ContentSelector.tsx
│   │   │   └── AnalysisPreview.tsx
│   │   ├── Thinker/                # System settings
│   │   │   ├── Dashboard.tsx
│   │   │   ├── Prompts.tsx
│   │   │   ├── AuthorProfiles.tsx
│   │   │   └── Strategies.tsx
│   │   ├── Billing/
│   │   │   ├── Credits.tsx
│   │   │   ├── Transactions.tsx
│   │   │   └── Usage.tsx
│   │   ├── Automation/
│   │   │   ├── Dashboard.tsx
│   │   │   ├── Rules.tsx
│   │   │   └── Tasks.tsx
│   │   └── Settings/
│   │       ├── General.tsx
│   │       ├── Users.tsx
│   │       ├── Subscriptions.tsx
│   │       ├── System.tsx
│   │       └── AI.tsx
│   │
│   ├── components/                 # Reusable components
│   │   ├── common/                 # Common UI components
│   │   ├── auth/                   # Auth components
│   │   ├── forms/                  # Form components
│   │   └── [module]/               # Module-specific components
│   │
│   ├── layout/                     # Layout components
│   │   ├── AppLayout.tsx           # Main app layout
│   │   ├── Sidebar.tsx             # Navigation sidebar
│   │   ├── Header.tsx              # Top header
│   │   └── Footer.tsx              # Footer
│   │
│   ├── hooks/                      # Custom React hooks
│   │   ├── useAuth.ts              # Auth hook
│   │   ├── useApi.ts               # API call hook
│   │   └── useSite.ts              # Site context hook
│   │
│   ├── services/                   # Business logic
│   │   ├── authService.ts          # Auth logic
│   │   └── apiService.ts           # API utilities
│   │
│   ├── config/                     # Configuration
│   │   └── constants.ts            # App constants
│   │
│   └── types/                      # TypeScript types
│       ├── api.ts                  # API types
│       └── models.ts               # Data model types
│
├── public/                         # Static assets
├── package.json                    # Node dependencies
├── vite.config.ts                  # Vite configuration
├── tsconfig.json                   # TypeScript configuration
└── tailwind.config.js              # Tailwind configuration
```

### State Management (Zustand)

**Auth Store** (`store/authStore.ts`)
```typescript
interface AuthState {
  user: User | null;
  token: string | null;
  refreshToken: string | null;
  isAuthenticated: boolean;
  login: (email: string, password: string) => Promise<void>;
  logout: () => void;
  refreshAccessToken: () => Promise<void>;
}
```

**Site Store** (`store/siteStore.ts`)
```typescript
interface SiteState {
  currentSite: Site | null;
  currentSector: Sector | null;
  sites: Site[];
  setSite: (site: Site) => void;
  setSector: (sector: Sector) => void;
}
```

---

## WordPress Plugin Deep Dive

### Plugin Structure

```
igny8-wp-integration/
├── igny8-bridge.php                # Main plugin file & bootstrap
├── uninstall.php                   # Cleanup on uninstall
│
├── includes/                       # Core classes
│   ├── class-igny8-api.php         # API client (authentication, requests)
│   ├── class-igny8-rest-api.php    # WP REST endpoints (/wp-json/igny8/v1/)
│   ├── class-igny8-site.php        # Site data collection
│   ├── class-igny8-webhooks.php    # Webhook handlers (incoming from IGNY8)
│   ├── class-igny8-webhook-logs.php # Webhook logging
│   ├── class-igny8-link-queue.php  # Link processing queue
│   └── functions.php               # Helper functions
│
├── admin/                          # WordPress admin UI
│   ├── class-admin.php             # Settings page controller
│   ├── settings.php                # Settings page UI
│   ├── class-admin-columns.php     # Custom post columns
│   ├── class-post-meta-boxes.php   # Post editor meta boxes
│   └── assets/
│       ├── css/admin.css           # Admin styles
│       └── js/
│           ├── admin.js            # Admin scripts
│           └── post-editor.js      # Post editor enhancements
│
├── sync/                           # Synchronization logic
│   ├── hooks.php                   # WordPress action/filter hooks
│   ├── post-sync.php               # WP → IGNY8 post sync
│   ├── taxonomy-sync.php           # WP → IGNY8 taxonomy sync
│   └── igny8-to-wp.php             # IGNY8 → WP content sync
│
├── data/                           # Data collection & mapping
│   ├── site-collection.php         # Full site data collection
│   ├── semantic-mapping.php        # Semantic metadata extraction
│   ├── link-graph.php              # Internal link graph builder
│   └── woocommerce.php             # WooCommerce integration
│
├── docs/                           # Plugin documentation
│   ├── WORDPRESS-PLUGIN-INTEGRATION.md
│   ├── AUTHENTICATION-AUDIT.md
│   └── SYNC-DATA-FLOW-DIAGRAM.md
│
└── tests/                          # Test scripts
    ├── test-api-authentication.php
    ├── test-site-metadata.php
    └── test-sync-structure.php
```

### Core Classes

#### Igny8API
**File:** `includes/class-igny8-api.php`

Handles all API communication with IGNY8 backend.

**Key Methods:**
- `connect($api_key, $site_id)` - Establish connection using API key
- `get($endpoint)` - GET request
- `post($endpoint, $data)` - POST request
- `put($endpoint, $data)` - PUT request
- `delete($endpoint)` - DELETE request
- `parse_response($response)` - Normalize API responses

**Authentication:**
- Primary: API key (stored in `igny8_api_key` option)
- Sends as `X-IGNY8-API-Key` header
- Automatic retry on 401 errors

#### Igny8RestAPI
**File:** `includes/class-igny8-rest-api.php`

Exposes WordPress data via REST API for IGNY8 to consume.

**Endpoints:**
- `GET /wp-json/igny8/v1/site-metadata/` - Site structure and metadata
- `GET /wp-json/igny8/v1/post-by-task-id/{task_id}` - Find post by IGNY8 task ID
- `GET /wp-json/igny8/v1/post-by-content-id/{content_id}` - Find post by content ID
- `POST /wp-json/igny8/v1/posts/` - Create post from IGNY8 content
- `PUT /wp-json/igny8/v1/posts/{id}` - Update post from IGNY8

**Authentication:**
- Accepts `X-IGNY8-API-Key` header
- Validates against stored API key

#### Igny8Site
**File:** `includes/class-igny8-site.php`

Collects and formats site data for IGNY8.

**Key Methods:**
- `get_site_metadata()` - Collect post types, taxonomies, counts
- `get_posts_data($post_type, $limit)` - Export posts
- `get_taxonomy_data($taxonomy, $limit)` - Export taxonomy terms
- `send_to_igny8()` - Push site data to IGNY8 API

### Sync Flow

#### WP → IGNY8 (Post Status Updates)

1. User edits/publishes post in WordPress
2. `save_post` hook triggers → `sync/post-sync.php`
3. Check if post has `_igny8_task_id` meta
4. Map WP status to IGNY8 status
5. Send PUT request to `/api/v1/writer/tasks/{task_id}/`
6. Update `_igny8_last_synced` meta

#### IGNY8 → WP (Content Publishing)

1. IGNY8 creates content via AI Writer
2. IGNY8 sends POST to `/wp-json/igny8/v1/posts/`
3. Plugin validates API key
4. Create WP post with content
5. Store `_igny8_task_id` and `_igny8_content_id` meta
6. Return post ID and URL to IGNY8

### Post Meta Fields

All IGNY8-managed posts use prefixed meta keys:

- `_igny8_task_id` - IGNY8 task ID
- `_igny8_content_id` - IGNY8 content ID
- `_igny8_wordpress_status` - Current WP status
- `_igny8_last_synced` - Last sync timestamp
- `_igny8_managed` - Flag for IGNY8-managed posts

---

## Integration Architecture

### WordPress ↔ IGNY8 Integration

```
┌─────────────────────────────────────────────────────────────────┐
│                    WordPress Site                                │
├─────────────────────────────────────────────────────────────────┤
│  IGNY8 Bridge Plugin                                             │
│  ─────────────────────────────────────────────────────────────  │
│  1. REST API Endpoints (/wp-json/igny8/v1/)                      │
│     • site-metadata (expose WP structure)                        │
│     • posts (CRUD operations)                                    │
│     • post-by-task-id (lookup)                                   │
│                                                                  │
│  2. Sync Handlers (sync/)                                        │
│     • post-sync.php (WP → IGNY8)                                 │
│     • igny8-to-wp.php (IGNY8 → WP)                               │
│                                                                  │
│  3. API Client (Igny8API class)                                  │
│     • Authentication (API key)                                   │
│     • Request/Response handling                                  │
└─────────────────────┬───────────────────────────────────────────┘
                      │
                      │ HTTPS REST API
                      │
                      ▼
┌─────────────────────────────────────────────────────────────────┐
│                IGNY8 Backend (Django)                            │
├─────────────────────────────────────────────────────────────────┤
│  Integration Module (/api/v1/integration/)                       │
│  ─────────────────────────────────────────────────────────────  │
│  1. IntegrationViewSet                                           │
│     • test-connection (validate WP connection)                   │
│     • update-structure (receive WP metadata)                     │
│     • sync (bidirectional sync trigger)                          │
│                                                                  │
│  2. SiteIntegration Model                                        │
│     • platform: 'wordpress'                                      │
│     • credentials_json: {api_key, username, app_password}        │
│     • config_json: {site_url, content_types, sync_settings}      │
│                                                                  │
│  3. Integration Services                                         │
│     • IntegrationService (connection testing)                    │
│     • SyncService (bidirectional sync)                           │
│     • ContentSyncService (content mapping)                       │
└─────────────────────────────────────────────────────────────────┘
```

### Authentication Flow

**Plugin → Backend:**
1. Plugin stores API key in WP options (`igny8_api_key`)
2. All API requests include `X-IGNY8-API-Key` header
3. Backend validates key against `Site.wp_api_key` field
4. Backend sets account context from API key

**Backend → Plugin:**
1. Backend sends requests to WP REST endpoints
2. Includes `X-IGNY8-API-Key` header
3. Plugin validates key matches stored value
4. Plugin processes request and returns unified response

---

## AI Framework

### Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                    AI Framework Entry Point                      │
├─────────────────────────────────────────────────────────────────┤
│  run_ai_task(function_name, payload, account, celery_task)      │
│  • Called from ViewSets for async AI operations                 │
│  • Wraps AI execution in Celery task                            │
└─────────────────────┬───────────────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────────────┐
│                      AIEngine                                    │
│  Location: igny8_core/ai/engine.py                              │
├─────────────────────────────────────────────────────────────────┤
│  • Central orchestrator for all AI functions                    │
│  • Progress tracking (Celery task updates)                      │
│  • Cost tracking (token usage)                                  │
│  • Retry logic                                                  │
│  • Error handling                                               │
│                                                                  │
│  Key Methods:                                                    │
│  • execute(function_name, payload) → result                     │
│  • _execute_function(func, data) → processes function           │
│  • _update_progress(step, status, message) → UI updates         │
└─────────────────────┬───────────────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────────────┐
│                   AI Function Registry                           │
│  Location: igny8_core/ai/registry.py                            │
├─────────────────────────────────────────────────────────────────┤
│  Registered Functions:                                           │
│  • auto_cluster (keywords → clusters)                           │
│  • generate_ideas (clusters → content ideas)                    │
│  • generate_content (ideas → blog posts)                        │
│  • generate_image_prompts (content → image prompts)             │
│  • generate_images (prompts → images)                           │
└─────────────────────┬───────────────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────────────┐
│                        AICore                                    │
│  Location: igny8_core/ai/ai_core.py                             │
├─────────────────────────────────────────────────────────────────┤
│  • Handles API calls to OpenAI/Runware                          │
│  • Model selection and configuration                            │
│  • Response parsing (JSON/text)                                 │
│  • Console logging                                              │
│  • Token counting and cost calculation                          │
│                                                                  │
│  Key Methods:                                                    │
│  • run_ai_request(prompt, model, ...) → AI response             │
│  • generate_image(prompt, model, ...) → image URL               │
│  • _call_openai_api(messages, model, ...) → raw response        │
│  • _parse_json_response(text) → parsed JSON                     │
└─────────────────────────────────────────────────────────────────┘
```

### AI Functions

#### auto_cluster
**File:** `ai/functions/auto_cluster.py`  
**Input:** List of keyword IDs  
**Output:** Clusters with assigned keywords  
**Model:** GPT-4 or configured model  
**Process:**
1. Load keywords from database
2. Build prompt with keyword list
3. Call AI to group semantically similar keywords
4. Parse JSON response
5. Create Cluster records
6. Assign keywords to clusters

#### generate_ideas
**File:** `ai/functions/generate_ideas.py`  
**Input:** List of cluster IDs  
**Output:** Content ideas for each cluster  
**Model:** GPT-4 or configured model  
**Process:**
1. Load clusters and keywords
2. Build prompt for content ideation
3. Call AI to generate ideas
4. Parse response
5. Create ContentIdea records

#### generate_content
**File:** `ai/functions/generate_content.py`  
**Input:** List of task IDs  
**Output:** Full blog posts with HTML  
**Model:** GPT-4 or configured model  
**Process:**
1. Load tasks and content ideas
2. Build detailed prompt with brief
3. Call AI to generate article
4. Parse HTML content
5. Create/update Content records
6. Update task status

#### generate_images
**File:** `ai/functions/generate_images.py`  
**Input:** List of task IDs with image prompts  
**Output:** Generated image URLs  
**Models:** DALL-E 3 or Runware  
**Process:**
1. Load tasks with image prompts
2. For each prompt, call image API
3. Upload images to storage
4. Create Image records
5. Link images to content

---

## Data Models

### Account & Auth Models

**Account** (`auth/models.py`)
```python
Account
├── name: str
├── slug: str (unique)
├── owner: User (FK)
├── plan: Plan (FK)
├── credits: int
├── status: str (active, suspended, trial, cancelled)
└── created_at, updated_at
```

**User** (`auth/models.py`)
```python
User (extends AbstractUser)
├── email: str (unique)
├── username: str (unique)
├── account: Account (FK)
├── role: str (developer, owner, admin, editor, viewer, system_bot)
└── is_active, is_staff, is_superuser
```

**Site** (`auth/models.py`)
```python
Site
├── account: Account (FK)
├── name: str
├── slug: str
├── domain: URL
├── industry: Industry (FK, nullable)
├── wordpress_url: URL
├── wordpress_username: str
├── wordpress_password: str (encrypted)
├── wp_api_key: str (for bridge auth)
├── status: str (active, inactive, suspended)
└── created_at, updated_at
```

**Sector** (`auth/models.py`)
```python
Sector
├── account: Account (FK)
├── site: Site (FK)
├── name: str
├── industry_sector: IndustrySector (FK, nullable)
├── status: str (active, inactive)
└── created_at, updated_at
```

### Planner Models

**Keywords** (`business/planning/models.py`)
```python
Keywords (inherits SiteSectorBaseModel)
├── account, site, sector (from base)
├── keyword: str
├── search_volume: int
├── difficulty: int
├── intent: str (informational, commercial, transactional, navigational)
├── status: str (active, inactive, used)
├── source: str (manual, csv_import, api_import)
└── created_at, updated_at
```

**Clusters** (`business/planning/models.py`)
```python
Clusters (inherits SiteSectorBaseModel)
├── account, site, sector (from base)
├── name: str
├── description: text
├── keywords: ManyToMany(Keywords)
├── status: str (active, archived)
└── created_at, updated_at
```

**ContentIdeas** (`business/planning/models.py`)
```python
ContentIdeas (inherits SiteSectorBaseModel)
├── account, site, sector (from base)
├── cluster: Cluster (FK)
├── title: str
├── description: text
├── suggested_keywords: JSON
├── status: str (draft, approved, in_progress, completed)
└── created_at, updated_at
```

### Writer Models

**Tasks** (`business/content/models.py`)
```python
Tasks (inherits SiteSectorBaseModel)
├── account, site, sector (from base)
├── content_idea: ContentIdea (FK, nullable)
├── cluster: Cluster (FK, nullable)
├── title: str
├── brief: text
├── target_keywords: JSON
├── status: str (pending, in_progress, completed, published)
├── assigned_post_id: int (WP post ID)
├── post_url: URL
├── content: Content (OneToOne, reverse)
└── created_at, updated_at
```

**Content** (`business/content/models.py`)
```python
Content (inherits SiteSectorBaseModel)
├── account, site, sector (from base)
├── task: Tasks (OneToOne, nullable)
├── title: str
├── content_html: text
├── content_plain: text
├── excerpt: text
├── meta_description: str
├── entity_type: str (post, page, product, service)
├── external_id: str (WP post ID)
├── external_type: str (post, page)
├── sync_status: str (draft, imported, synced, published)
├── taxonomies: ManyToMany(ContentTaxonomy)
├── attributes: JSON
└── created_at, updated_at
```

**Images** (`business/content/models.py`)
```python
Images (inherits SiteSectorBaseModel)
├── account, site, sector (from base)
├── task: Tasks (FK)
├── image_url: URL
├── prompt: text
├── is_featured: bool
├── position: int
├── alt_text: str
├── caption: str
└── created_at, updated_at
```

### Integration Models

**SiteIntegration** (`business/integration/models.py`)
```python
SiteIntegration
├── account: Account (FK)
├── site: Site (FK)
├── platform: str (wordpress, shopify, wix)
├── platform_type: str (cms, ecommerce, builder)
├── config_json: JSON (site_url, content_types, sync_settings)
├── credentials_json: JSON (api_key, username, app_password)
├── is_active: bool
├── sync_enabled: bool
├── last_sync_at: datetime
└── created_at, updated_at
```

---

## API Reference

### Base URL

```
Production: https://api.igny8.com/api/v1/
Development: http://localhost:8000/api/v1/
```

### Unified Response Format

All endpoints return:

```json
{
  "success": true,
  "data": { ... },
  "message": "Success message",
  "request_id": "uuid",
  "count": 100,        // For paginated endpoints
  "next": "url",       // Pagination
  "previous": "url",   // Pagination
  "results": [...]     // Paginated data
}
```

Error response:
```json
{
  "success": false,
  "error": "Error message",
  "errors": {...},     // Field-level errors
  "request_id": "uuid"
}
```

### Authentication

**Login:**
```http
POST /api/v1/auth/login/
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "password"
}

Response:
{
  "success": true,
  "data": {
    "access": "jwt_token",
    "refresh": "refresh_token",
    "user": {...}
  }
}
```

**Use Token:**
```http
GET /api/v1/planner/keywords/
Authorization: Bearer {access_token}
```

### Key Endpoints by Module

#### Planner Module

```
GET    /api/v1/planner/keywords/               # List keywords
POST   /api/v1/planner/keywords/               # Create keyword
GET    /api/v1/planner/keywords/{id}/          # Get keyword
PUT    /api/v1/planner/keywords/{id}/          # Update keyword
DELETE /api/v1/planner/keywords/{id}/          # Delete keyword
POST   /api/v1/planner/keywords/bulk_create/   # Bulk import
POST   /api/v1/planner/keywords/auto_cluster/  # AI clustering

GET    /api/v1/planner/clusters/               # List clusters
POST   /api/v1/planner/clusters/               # Create cluster
POST   /api/v1/planner/clusters/generate_ideas/ # AI idea generation

GET    /api/v1/planner/ideas/                  # List ideas
POST   /api/v1/planner/ideas/                  # Create idea
```

#### Writer Module

```
GET    /api/v1/writer/tasks/                   # List tasks
POST   /api/v1/writer/tasks/                   # Create task
GET    /api/v1/writer/tasks/{id}/              # Get task
PUT    /api/v1/writer/tasks/{id}/              # Update task
POST   /api/v1/writer/tasks/generate_content/  # AI content generation
POST   /api/v1/writer/tasks/generate_images/   # AI image generation

GET    /api/v1/writer/content/                 # List content
GET    /api/v1/writer/content/{id}/            # Get content

GET    /api/v1/writer/images/                  # List images
```

#### Integration Module

```
GET    /api/v1/integration/integrations/       # List integrations
POST   /api/v1/integration/integrations/       # Create integration
POST   /api/v1/integration/integrations/test-connection/  # Test WP connection
POST   /api/v1/integration/integrations/{id}/update-structure/  # Update WP metadata
GET    /api/v1/integration/integrations/{id}/content-types/  # Get content types
POST   /api/v1/integration/integrations/{id}/sync/  # Trigger sync
```

#### System Module

```
GET    /api/v1/system/prompts/                 # List AI prompts
POST   /api/v1/system/prompts/                 # Create prompt
GET    /api/v1/system/author-profiles/         # List author profiles
GET    /api/v1/system/settings/                # System settings
```

#### Billing Module

```
GET    /api/v1/billing/balance/                # Get credit balance
GET    /api/v1/billing/transactions/           # List transactions
GET    /api/v1/billing/usage/                  # Usage analytics
```

---

## Workflows

### 1. Keyword to Published Post (Full Workflow)

```
1. Import Keywords
   ↓
   POST /api/v1/planner/keywords/bulk_create/
   • Upload CSV or manual entry
   • Keywords stored in database

2. AI Clustering
   ↓
   POST /api/v1/planner/keywords/auto_cluster/
   • Celery task: auto_cluster
   • AI groups keywords → Clusters
   • Keywords assigned to clusters

3. Generate Content Ideas
   ↓
   POST /api/v1/planner/clusters/generate_ideas/
   • Celery task: generate_ideas
   • AI creates ContentIdeas from clusters

4. Create Writer Task
   ↓
   POST /api/v1/writer/tasks/
   • Link task to ContentIdea
   • Set brief and target keywords

5. Generate Content
   ↓
   POST /api/v1/writer/tasks/generate_content/
   • Celery task: generate_content
   • AI writes full blog post → Content record
   • Task status: completed

6. Generate Images (optional)
   ↓
   POST /api/v1/writer/tasks/generate_images/
   • Celery task: generate_images
   • AI creates images → Image records

7. Publish to WordPress
   ↓
   POST /wp-json/igny8/v1/posts/
   • IGNY8 sends content to WP plugin
   • Plugin creates WP post
   • Stores _igny8_task_id meta

8. Status Sync (WP → IGNY8)
   ↓
   PUT /api/v1/writer/tasks/{id}/
   • User publishes in WP
   • Plugin syncs status back to IGNY8
```

### 2. WordPress Integration Setup

```
1. Install Plugin
   ↓
   • Upload igny8-bridge.zip to WordPress
   • Activate plugin

2. Generate API Key (IGNY8 App)
   ↓
   • Login to app.igny8.com
   • Navigate to Settings → Sites
   • Generate API key for site

3. Connect Plugin
   ↓
   • In WP admin: Settings → IGNY8 API
   • Enter email, password, API key
   • Click "Test Connection"

4. Initial Sync
   ↓
   • Plugin sends site metadata to IGNY8
   • POST /api/v1/integration/integrations/test-connection/
   • IGNY8 creates SiteIntegration record

5. Ongoing Sync
   ↓
   • WP → IGNY8: Post status updates (save_post hook)
   • IGNY8 → WP: Content publishing (REST API)
```

---

## Developer Navigation Map

### "I need to..."

#### Add a new API endpoint
1. Create method in ViewSet (`modules/[module]/views.py`)
2. Use `@action` decorator for custom endpoints
3. Add route to `urls.py` if needed
4. Return `success_response()` or `error_response()`

#### Add a new model field
1. Edit model in `business/[domain]/models.py`
2. Run `python manage.py makemigrations`
3. Run `python manage.py migrate`
4. Update serializers in `modules/[module]/serializers.py`

#### Add AI functionality
1. Create function class in `ai/functions/[name].py`
2. Inherit from `BaseAIFunction`
3. Implement `validate()`, `prepare()`, `execute()`, `save()`
4. Register in `ai/registry.py`
5. Call via `run_ai_task()` from ViewSet

#### Debug API call
1. Check request ID in response
2. Search logs: `grep {request_id} logs/`
3. Check middleware: `RequestIDMiddleware`
4. Check account context: `AccountContextMiddleware`

#### Add WordPress sync logic
1. Add hook in `sync/hooks.php`
2. Implement handler in `sync/post-sync.php` or `sync/taxonomy-sync.php`
3. Use `Igny8API` class for API calls
4. Update post meta with `_igny8_*` keys

#### Add frontend page
1. Create component in `frontend/src/pages/[Module]/[Page].tsx`
2. Add route in `App.tsx`
3. Add to sidebar navigation in `layout/Sidebar.tsx`
4. Create API calls in `api/[module].ts`
5. Use Zustand store for state

---

## Troubleshooting Map

### Common Issues and Where to Look

#### "Authentication failed / 401 errors"
**Check:**
- `igny8_core/auth/middleware.py` - AccountContextMiddleware
- JWT token expiry - tokens expire in 15 minutes
- API key validation - `Site.wp_api_key` field
- Plugin: `includes/class-igny8-api.php` - connect() method

#### "Posts not syncing to IGNY8"
**Check:**
- `sync/hooks.php` - save_post hook registered?
- `sync/post-sync.php` - igny8_sync_post_status_to_igny8()
- Post meta: `_igny8_task_id` exists?
- `igny8_is_connection_enabled()` returns true?
- API key stored: `get_option('igny8_api_key')`

#### "AI task stuck/failed"
**Check:**
- Celery worker running: `celery -A igny8_core worker -l info`
- Task logs: Check Celery console output
- `ai/engine.py` - AIEngine.execute()
- `ai/ai_core.py` - APICore.run_ai_request()
- Credit balance: Check `Account.credits`
- Model configuration: `system/models.py` - IntegrationSettings

#### "Frontend can't fetch data"
**Check:**
- CORS settings: `igny8_core/settings.py` - CORS_ALLOWED_ORIGINS
- API base URL: `frontend/src/api/client.ts`
- Auth token: Check `authStore` in browser DevTools
- Network tab: Check request/response
- Backend logs: Check for errors

#### "WordPress plugin can't connect"
**Check:**
- API key matches: WP option vs `Site.wp_api_key`
- Site URL correct: WP site URL vs `SiteIntegration.config_json.site_url`
- REST API enabled: Test `/wp-json/` endpoint
- PHP errors: Check WP debug log
- Connection test: `includes/class-igny8-api.php` - connect()

#### "Rate limiting errors"
**Check:**
- `api/throttles.py` - DebugScopedRateThrottle
- `settings.py` - IGNY8_DEBUG_THROTTLE flag
- User role has sufficient permissions
- Check throttle scope in ViewSet

#### "Account isolation not working"
**Check:**
- `auth/middleware.py` - AccountContextMiddleware sets request.account?
- ViewSet inherits from `AccountModelViewSet` or `SiteSectorModelViewSet`?
- JWT token contains `account_id`?
- Query filtering: `get_queryset()` filters by account?

---

## File Quick Reference

### Most Important Files

| File | Purpose | When to Check |
|------|---------|---------------|
| `backend/igny8_core/settings.py` | Django configuration | Environment issues, installed apps |
| `backend/igny8_core/urls.py` | URL routing | Adding endpoints, 404 errors |
| `backend/igny8_core/celery.py` | Celery config | Task queue issues |
| `backend/igny8_core/auth/models.py` | Account, User, Site models | Multi-tenancy, auth issues |
| `backend/igny8_core/auth/middleware.py` | Account context | Request.account issues |
| `backend/igny8_core/api/base.py` | Base ViewSets | Queryset filtering |
| `backend/igny8_core/ai/engine.py` | AI orchestrator | AI task failures |
| `backend/igny8_core/ai/ai_core.py` | AI API calls | OpenAI errors |
| `frontend/src/App.tsx` | Frontend routing | Navigation issues |
| `frontend/src/store/authStore.ts` | Auth state | Login/logout issues |
| `frontend/src/api/client.ts` | API client | API call failures |
| `igny8-wp-integration/igny8-bridge.php` | Plugin bootstrap | Plugin initialization |
| `igny8-wp-integration/includes/class-igny8-api.php` | WP API client | API communication |
| `igny8-wp-integration/includes/class-igny8-rest-api.php` | WP REST endpoints | Endpoint errors |
| `igny8-wp-integration/sync/post-sync.php` | WP → IGNY8 sync | Sync failures |

---

## Technology Dependencies

### Backend

```
Django==5.2.7
djangorestframework
psycopg2-binary       # PostgreSQL
redis                 # Celery broker
celery==5.3.0
PyJWT==2.8.0
requests==2.31.0
beautifulsoup4==4.12.0
drf-spectacular==0.27.0
django-filter
django-cors-headers
whitenoise
gunicorn
```

### Frontend

```
react==19.0.0
react-dom==19.0.0
react-router==7.1.5
react-router-dom==7.9.5
zustand==5.0.8
vite==6.1.0
typescript==5.7.2
tailwindcss==4.0.8
apexcharts==4.1.0
@heroicons/react==2.2.0
```

### WordPress Plugin

```
PHP >= 7.4
WordPress >= 5.0
```

---

## Deployment Architecture

### Production Stack

```
┌─────────────────────────────────────────────────────────────────┐
│                          Caddy                                   │
│                    (Reverse Proxy + SSL)                         │
└─────────────────────┬───────────────────────────────────────────┘
                      │
          ┌───────────┴───────────┐
          ▼                       ▼
┌──────────────────┐    ┌──────────────────┐
│  Frontend (Vite) │    │  Backend (Gunicorn)│
│  app.igny8.com   │    │  api.igny8.com     │
│  Port: 5173      │    │  Port: 8000        │
└──────────────────┘    └─────────┬──────────┘
                                  │
                  ┌───────────────┴───────────────┐
                  ▼                               ▼
        ┌──────────────────┐          ┌──────────────────┐
        │  PostgreSQL      │          │  Redis           │
        │  Database        │          │  Celery Broker   │
        └──────────────────┘          └─────────┬────────┘
                                                 │
                                                 ▼
                                      ┌──────────────────┐
                                      │  Celery Worker   │
                                      │  AI Tasks        │
                                      └──────────────────┘
```

### Docker Compose

See `docker-compose.app.yml` for full configuration.

---

**End of Master Reference**

For setup instructions, see `README.md`.  
For version history, see `CHANGELOG.md`.  
For API details, see `master-docs/API-COMPLETE-REFERENCE.md`.