# 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

# Stage 1 Changes (Nov 2025):
# REMOVED: context_type, dimension_meta
# Now pure topic-based clustering
```

**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)
├── cluster: Cluster (FK, nullable)
├── title: str
├── description: text (brief)
├── keywords: JSON (target keywords)
├── content_type: str (post, page, product, etc.)
├── content_structure: JSON (template for content generation)
├── taxonomy_term_id: int (optional categorization)
├── status: str (queued, completed)  # Simplified in Stage 1
├── assigned_post_id: int (WP post ID)
├── post_url: URL
└── created_at, updated_at

# Stage 1 Changes (Nov 2025):
# REMOVED: content_idea FK, cluster_role, entity_type, cluster_context, dimension_roles, metadata, content_record
# ADDED: content_type, content_structure, taxonomy_term_id
# CHANGED: status simplified to (queued, completed)
```

**Content** (`business/content/models.py`)
```python
Content (inherits SiteSectorBaseModel)
├── account, site, sector (from base)
├── cluster_id: int (cluster reference)
├── title: str
├── content_html: text (generated HTML content)
├── content_type: str (post, page, product, etc.)
├── content_structure: JSON (structure template used)
├── taxonomy_terms: ManyToMany(ContentTaxonomy)  # Direct M2M
├── external_id: str (WP post ID)
├── external_url: URL (published URL)
├── source: str (igny8, wordpress, import)
├── status: str (draft, published)  # Simplified in Stage 1
└── created_at, updated_at

# Stage 1 Changes (Nov 2025):
# REMOVED: task FK, html_content, word_count, metadata, meta_title, meta_description,
#          primary_keyword, secondary_keywords, entity_type, json_blocks, structure_data,
#          content_format, cluster_role, sync_status, external_type, external_status,
#          sync_data, last_synced_at, validation_errors, is_validated
# ADDED: cluster_id, title, content_html, content_type, content_structure
# CHANGED: status simplified to (draft, published)
# CHANGED: taxonomy relationship from through model to direct M2M
```

**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
```

**ContentTaxonomy** (`business/content/models.py`)
```python
ContentTaxonomy (inherits SiteSectorBaseModel)
├── account, site, sector (from base)
├── name: str
├── slug: str
├── taxonomy_type: str (category, post_tag, cluster)
├── external_id: str (WordPress taxonomy term ID)
├── external_taxonomy: str (WordPress taxonomy name)
└── created_at, updated_at

# Stage 1 Changes (Nov 2025):
# REMOVED: description, parent FK, sync_status, count, metadata, clusters M2M
# ADDED: 'cluster' as taxonomy_type option
# Simplified to essential fields for WP sync
```

### 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
```

---

## Portable Package Structure

This section defines the **essential files and folders** needed to deploy IGNY8 to a new infrastructure with the same tech stack. These are IGNY8-specific application files (excluding standard framework boilerplate that gets installed via package managers).

### Backend Essential Package Tree

**Package Only These Files** - Excludes Django-generated boilerplate and dependencies installed via pip:

```
backend/
├── manage.py                          # Django entry point (IGNY8-configured)
├── requirements.txt                   # Python dependencies (essential)
├── Dockerfile                         # Container configuration (essential)
│
└── igny8_core/                        # Main Django project
    ├── __init__.py                    # Project marker
    ├── settings.py                    # ⭐ IGNY8 configuration (critical)
    ├── test_settings.py               # Test configuration
    ├── urls.py                        # Main URL routing (IGNY8-specific)
    ├── asgi.py                        # ASGI entry point
    ├── wsgi.py                        # WSGI entry point
    ├── celery.py                      # ⭐ Celery configuration (critical)
    │
    ├── admin/                         # Custom Django admin
    │   ├── __init__.py
    │   ├── apps.py
    │   ├── base.py                    # Admin base classes
    │   └── site.py                    # Custom admin site
    │
    ├── auth/                          # ⭐ Authentication module (critical)
    │   ├── __init__.py
    │   ├── apps.py
    │   ├── admin.py
    │   ├── models.py                  # User, Account, Site models
    │   ├── serializers.py
    │   ├── views.py
    │   ├── urls.py
    │   ├── permissions.py
    │   ├── middleware.py              # Account context middleware
    │   ├── utils.py
    │   └── management/
    │       └── commands/              # Custom management commands
    │
    ├── ai/                            # ⭐ AI Framework (critical)
    │   ├── __init__.py
    │   ├── apps.py
    │   ├── admin.py
    │   ├── models.py                  # AIJob, AITaskResult
    │   ├── base.py                    # Base AI classes
    │   ├── ai_core.py                 # Core AI logic
    │   ├── engine.py                  # AI execution engine
    │   ├── registry.py                # AI function registry
    │   ├── prompts.py                 # AI prompt templates
    │   ├── validators.py
    │   ├── tracker.py                 # Progress tracking
    │   ├── tasks.py                   # Celery tasks
    │   ├── settings.py                # AI configuration
    │   ├── constants.py
    │   ├── functions/                 # AI function implementations
    │   │   ├── __init__.py
    │   │   ├── base.py
    │   │   ├── content_generation.py
    │   │   ├── image_generation.py
    │   │   └── ...
    │   ├── migrations/                # Database migrations (critical)
    │   └── tests/
    │
    ├── api/                           # ⭐ API Infrastructure (critical)
    │   ├── __init__.py
    │   ├── base.py                    # Base ViewSet classes
    │   ├── response.py                # Unified response format
    │   ├── pagination.py              # Pagination classes
    │   ├── permissions.py             # API permissions
    │   ├── authentication.py          # JWT authentication
    │   ├── throttles.py               # Rate limiting
    │   ├── exception_handlers.py      # Error handling
    │   ├── schema_extensions.py       # OpenAPI schema
    │   ├── wordpress_publishing.py    # WordPress integration
    │   └── tests/
    │
    ├── business/                      # ⭐ Business Logic Layer (critical)
    │   ├── __init__.py
    │   ├── planning/
    │   │   ├── __init__.py
    │   │   ├── cluster_service.py
    │   │   ├── keyword_service.py
    │   │   └── idea_service.py
    │   ├── content/
    │   │   ├── __init__.py
    │   │   ├── generation_service.py
    │   │   └── image_service.py
    │   ├── linking/
    │   │   ├── __init__.py
    │   │   └── linking_service.py
    │   ├── optimization/
    │   │   ├── __init__.py
    │   │   └── optimization_service.py
    │   ├── publishing/
    │   │   ├── __init__.py
    │   │   └── wordpress_service.py
    │   ├── site_building/
    │   │   ├── __init__.py
    │   │   └── builder_service.py
    │   ├── automation/
    │   │   ├── __init__.py
    │   │   └── automation_service.py
    │   ├── integration/
    │   │   ├── __init__.py
    │   │   └── integration_service.py
    │   └── billing/
    │       ├── __init__.py
    │       └── credit_service.py
    │
    ├── modules/                       # ⭐ Feature Modules (critical)
    │   ├── __init__.py
    │   │
    │   ├── planner/                   # Keyword planning
    │   │   ├── __init__.py
    │   │   ├── apps.py
    │   │   ├── admin.py
    │   │   ├── models.py
    │   │   ├── serializers.py
    │   │   ├── cluster_serializers.py
    │   │   ├── views.py
    │   │   ├── urls.py
    │   │   ├── migrations/
    │   │   └── management/
    │   │
    │   ├── writer/                    # Content generation
    │   │   ├── __init__.py
    │   │   ├── apps.py
    │   │   ├── admin.py
    │   │   ├── models.py
    │   │   ├── serializers.py
    │   │   ├── views.py
    │   │   ├── urls.py
    │   │   ├── migrations/
    │   │   └── management/
    │   │
    │   ├── linker/                    # Internal linking
    │   │   ├── __init__.py
    │   │   ├── apps.py
    │   │   ├── admin.py
    │   │   ├── models.py
    │   │   ├── serializers.py
    │   │   ├── views.py
    │   │   ├── urls.py
    │   │   └── migrations/
    │   │
    │   ├── optimizer/                 # Content optimization
    │   │   ├── __init__.py
    │   │   ├── apps.py
    │   │   ├── admin.py
    │   │   ├── models.py
    │   │   ├── serializers.py
    │   │   ├── views.py
    │   │   ├── urls.py
    │   │   └── migrations/
    │   │
    │   ├── publisher/                 # WordPress publishing
    │   │   ├── __init__.py
    │   │   ├── apps.py
    │   │   ├── views.py
    │   │   └── urls.py
    │   │
    │   ├── site_builder/             # Site blueprints
    │   │   ├── __init__.py
    │   │   ├── apps.py
    │   │   ├── admin.py
    │   │   ├── models.py
    │   │   ├── serializers.py
    │   │   ├── views.py
    │   │   ├── urls.py
    │   │   └── migrations/
    │   │
    │   ├── automation/               # Task automation
    │   │   ├── __init__.py
    │   │   ├── apps.py
    │   │   ├── admin.py
    │   │   ├── models.py
    │   │   ├── serializers.py
    │   │   ├── views.py
    │   │   ├── urls.py
    │   │   └── migrations/
    │   │
    │   ├── integration/              # WordPress integration
    │   │   ├── __init__.py
    │   │   ├── apps.py
    │   │   ├── views.py
    │   │   └── urls.py
    │   │
    │   ├── billing/                  # Credit system
    │   │   ├── __init__.py
    │   │   ├── apps.py
    │   │   ├── admin.py
    │   │   ├── models.py
    │   │   ├── serializers.py
    │   │   ├── views.py
    │   │   ├── urls.py
    │   │   └── migrations/
    │   │
    │   └── system/                   # System settings
    │       ├── __init__.py
    │       ├── apps.py
    │       ├── admin.py
    │       ├── models.py              # Settings, AI models
    │       ├── serializers.py
    │       ├── settings_models.py
    │       ├── settings_serializers.py
    │       ├── settings_views.py
    │       ├── settings_admin.py
    │       ├── views.py
    │       ├── integration_views.py
    │       ├── urls.py
    │       ├── validators.py
    │       ├── utils.py
    │       ├── schemas.py
    │       ├── management/
    │       └── migrations/
    │
    ├── middleware/                    # Custom middleware
    │   ├── __init__.py
    │   ├── request_id.py              # Request ID tracking
    │   └── resource_tracker.py        # Resource monitoring
    │
    ├── tasks/                         # Celery tasks
    │   └── wordpress_publishing.py
    │
    ├── utils/                         # Shared utilities
    │   ├── __init__.py
    │   ├── ai_processor.py
    │   ├── content_normalizer.py
    │   ├── queue_manager.py
    │   └── wordpress.py
    │
    ├── urls/                          # URL modules
    │   └── [module-specific URL configs]
    │
    └── migrations/                    # ⭐ Database migrations (critical)
        └── [all migration files]
```

**EXCLUDE from package (installed via package managers):**
- `.venv/` - Virtual environment (created on deployment)
- `__pycache__/` - Python cache files
- `*.pyc`, `*.pyo` - Compiled Python
- `staticfiles/` - Collected static files (generated)
- `logs/` - Log files
- `db.sqlite3`, `*.sql` - Database files
- `celerybeat-schedule` - Celery scheduler state
- Test/debug scripts: `check_*.py`, `fix_*.py`, `verify_*.py`, `diagnose_*.py`, `inject_*.py`, `test_*.py`
- `backup_*.sql` - Database backups

### Frontend Essential Package Tree

**Package Only These Files** - Excludes React boilerplate and node_modules:

```
frontend/
├── package.json                       # ⭐ Dependencies manifest (critical)
├── package-lock.json                  # Locked dependencies
├── tsconfig.json                      # TypeScript config (IGNY8-modified)
├── tsconfig.app.json                  # App-specific TS config
├── tsconfig.node.json                 # Node-specific TS config
├── vite.config.ts                     # ⭐ Vite build config (IGNY8-customized)
├── vitest.config.ts                   # Test configuration
├── postcss.config.js                  # PostCSS config
├── eslint.config.js                   # ESLint configuration
├── index.html                         # Main HTML entry point
├── marketing.html                     # Marketing site entry (if used)
├── Dockerfile                         # ⭐ Container config (critical)
├── Dockerfile.dev                     # Dev container config
├── Caddyfile                          # Reverse proxy config
│
├── public/                            # Static assets
│   ├── images/                        # IGNY8 images
│   └── marketing/                     # Marketing assets
│
└── src/                               # ⭐ Application source (all critical)
    ├── main.tsx                       # ⭐ App entry point (IGNY8-specific)
    ├── App.tsx                        # ⭐ Main app component (IGNY8 routing)
    ├── index.css                      # Global styles
    ├── vite-env.d.ts                  # Vite type definitions
    ├── svg.d.ts                       # SVG type definitions
    │
    ├── config/                        # ⭐ App configuration
    │   ├── api.config.ts              # API endpoints
    │   ├── routes.config.ts           # Route definitions
    │   └── constants.ts               # App constants
    │
    ├── types/                         # ⭐ TypeScript types (IGNY8 models)
    │   ├── index.ts
    │   ├── auth.types.ts
    │   ├── planner.types.ts
    │   ├── writer.types.ts
    │   ├── linker.types.ts
    │   ├── optimizer.types.ts
    │   ├── site.types.ts
    │   ├── billing.types.ts
    │   └── ...
    │
    ├── api/                           # ⭐ API client layer
    │   ├── automation.api.ts
    │   ├── linker.api.ts
    │   └── optimizer.api.ts
    │
    ├── services/                      # ⭐ Service layer
    │   ├── api.ts                     # Base API service
    │   ├── integration.api.ts
    │   └── siteBuilder.api.ts
    │
    ├── store/                         # ⭐ Zustand state management
    │   ├── authStore.ts
    │   ├── billingStore.ts
    │   ├── plannerStore.ts
    │   ├── siteStore.ts
    │   ├── siteDefinitionStore.ts
    │   ├── settingsStore.ts
    │   ├── sectorStore.ts
    │   ├── onboardingStore.ts
    │   ├── columnVisibilityStore.ts
    │   └── pageSizeStore.ts
    │
    ├── context/                       # React Context providers
    │   ├── ThemeContext.tsx
    │   └── HeaderMetricsContext.tsx
    │
    ├── hooks/                         # Custom React hooks
    │   ├── useAuth.ts
    │   ├── useDebounce.ts
    │   ├── useLocalStorage.ts
    │   └── ...
    │
    ├── layout/                        # ⭐ App layout components
    │   ├── AppLayout.tsx              # Main layout
    │   ├── AppHeader.tsx              # Header
    │   ├── AppSidebar.tsx             # Sidebar navigation
    │   ├── SidebarWidget.tsx
    │   └── Backdrop.tsx
    │
    ├── components/                    # ⭐ IGNY8-specific components
    │   ├── auth/                      # Authentication
    │   │   ├── ProtectedRoute.tsx
    │   │   └── ...
    │   │
    │   ├── common/                    # Shared components
    │   │   ├── ErrorBoundary.tsx
    │   │   ├── LoadingStateMonitor.tsx
    │   │   ├── GlobalErrorDisplay.tsx
    │   │   ├── ScrollToTop.tsx
    │   │   ├── ModuleGuard.tsx
    │   │   └── ...
    │   │
    │   ├── header/                    # Header components
    │   ├── sidebar/                   # Sidebar components
    │   ├── navigation/                # Navigation
    │   ├── dashboard/                 # Dashboard widgets
    │   ├── content/                   # Content components
    │   ├── integration/               # Integration UI
    │   ├── linker/                    # Linker components
    │   ├── optimizer/                 # Optimizer components
    │   ├── publishing/                # Publishing UI
    │   ├── sites/                     # Site management
    │   ├── tasks/                     # Task management
    │   ├── onboarding/                # Onboarding flow
    │   ├── debug/                     # Debug tools
    │   │
    │   ├── ui/                        # UI primitives
    │   │   ├── toast/
    │   │   ├── button/
    │   │   ├── modal/
    │   │   └── ...
    │   │
    │   ├── tables/                    # Table components
    │   ├── form/                      # Form components
    │   ├── charts/                    # Chart components
    │   └── shared/                    # Shared UI
    │
    ├── pages/                         # ⭐ Page components (routes)
    │   ├── Dashboard/
    │   │   └── Home.tsx               # Main dashboard
    │   │
    │   ├── AuthPages/                 # Auth pages
    │   │   ├── SignIn.tsx
    │   │   └── SignUp.tsx
    │   │
    │   ├── Planner/                   # Planner module
    │   │   ├── Dashboard.tsx
    │   │   ├── Keywords.tsx
    │   │   ├── Clusters.tsx
    │   │   ├── ClusterDetail.tsx
    │   │   ├── Ideas.tsx
    │   │   └── KeywordOpportunities.tsx
    │   │
    │   ├── Writer/                    # Writer module
    │   │   ├── Dashboard.tsx
    │   │   ├── Tasks.tsx
    │   │   ├── ContentLibrary.tsx
    │   │   └── ...
    │   │
    │   ├── Linker/                    # Linker module
    │   ├── Optimizer/                 # Optimizer module
    │   ├── Sites/                     # Site management
    │   ├── Settings/                  # Settings
    │   ├── Billing/                   # Billing
    │   ├── Automation/                # Automation
    │   ├── Help/                      # Help pages
    │   ├── Setup/                     # Setup wizard
    │   ├── Reference/                 # Reference pages
    │   ├── Thinker/                   # Thinker module
    │   └── OtherPage/
    │       └── NotFound.tsx
    │
    ├── modules/                       # Module-specific logic
    │   └── siteBuilder/
    │
    ├── templates/                     # Page templates
    ├── icons/                         # Custom icons
    ├── styles/                        # ⭐ IGNY8 styles
    │   └── igny8-colors.css           # Custom color scheme
    │
    ├── utils/                         # Utility functions
    │   ├── dateUtils.ts
    │   ├── formatters.ts
    │   └── ...
    │
    ├── marketing/                     # Marketing site (optional)
    │   └── [marketing components]
    │
    └── __tests__/                     # Tests
        └── [test files]
```

**EXCLUDE from package (installed via npm):**
- `node_modules/` - Dependencies (installed via `npm install`)
- `dist/` - Build output (generated)
- `banner.png` - May be optional
- `DESIGN_SYSTEM.md`, `MIGRATION_GUIDE.md`, `README.md`, `LICENSE.md` - Documentation (optional)

### Installation & Portability Guide

#### Backend Deployment Steps

```bash
# 1. Copy backend essential files to new infrastructure
# 2. Set up Python environment
python -m venv .venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows

# 3. Install dependencies from requirements.txt
pip install -r requirements.txt

# 4. Configure environment variables (create .env file)
SECRET_KEY=<generate-new-secret-key>
DEBUG=False
DATABASE_URL=postgresql://user:pass@host:5432/dbname
REDIS_URL=redis://redis:6379/0
ALLOWED_HOSTS=yourdomain.com

# 5. Run migrations to set up database
python manage.py migrate

# 6. Create superuser
python manage.py createsuperuser

# 7. Collect static files
python manage.py collectstatic --noinput

# 8. Start services
# Application server
gunicorn igny8_core.wsgi:application --bind 0.0.0.0:8000

# Celery worker (separate terminal)
celery -A igny8_core worker --loglevel=info

# Celery beat scheduler (separate terminal)
celery -A igny8_core beat --loglevel=info
```

#### Frontend Deployment Steps

```bash
# 1. Copy frontend essential files to new infrastructure
# 2. Install dependencies from package.json
npm install
# or
npm ci  # for production (uses package-lock.json)

# 3. Configure environment (create .env file)
VITE_API_BASE_URL=https://api.yourdomain.com
VITE_APP_NAME=IGNY8

# 4. Build for production
npm run build

# 5. Serve static files (multiple options)
# Option A: Using Caddy (recommended)
caddy run --config Caddyfile

# Option B: Using preview mode
npm run preview

# Option C: Using static server
npx serve -s dist -l 5173
```

#### Docker Deployment (Recommended)

```bash
# Build and run with Docker Compose
docker-compose -f docker-compose.app.yml up -d

# Services will be available at:
# - Frontend: http://localhost:5173
# - Backend API: http://localhost:8000
# - Admin: http://localhost:8000/igny8-admin/
```

### Key Differences: Framework Files vs IGNY8 Files

#### Backend

**Framework Files (NOT in package):**
- Django's own code (installed via pip)
- Standard Django project structure created by `django-admin startproject`
- Generic migration files for Django's contrib apps
- Python standard library modules

**IGNY8-Specific Files (IN package):**
- All files in `igny8_core/` with custom business logic
- Custom models, views, serializers, URLs
- AI framework implementation
- Business logic services
- Module-specific code (planner, writer, linker, etc.)
- Custom middleware and utilities
- Database migrations for IGNY8 models
- `settings.py` with IGNY8 configuration
- `requirements.txt` (dependency manifest)

#### Frontend

**Framework Files (NOT in package):**
- React library itself (installed via npm)
- node_modules dependencies
- TypeScript compiler
- Vite build tool
- TailwindCSS framework

**IGNY8-Specific Files (IN package):**
- All `.tsx` and `.ts` files in `src/`
- Custom components, pages, layouts
- State management stores
- API client implementation
- Type definitions for IGNY8 models
- Custom hooks and utilities
- Routing configuration
- Custom styles (`igny8-colors.css`)
- `package.json` (dependency manifest)
- `vite.config.ts` with IGNY8-specific build config

### Portability Checklist

✅ **Before packaging:**
- [ ] Remove all `.env` files (environment-specific)
- [ ] Remove database files (`.sqlite3`, `*.sql` backups)
- [ ] Remove logs and temporary files
- [ ] Remove virtual environments (`.venv/`, `node_modules/`)
- [ ] Remove build artifacts (`dist/`, `staticfiles/`, `__pycache__/`)
- [ ] Keep all migration files (critical for database schema)
- [ ] Keep `requirements.txt` and `package.json` (dependency manifests)
- [ ] Keep Dockerfile and docker-compose files

✅ **After deployment to new infrastructure:**
- [ ] Install dependencies (`pip install -r requirements.txt`, `npm install`)
- [ ] Configure environment variables for new infrastructure
- [ ] Run database migrations
- [ ] Create initial superuser
- [ ] Collect static files (backend)
- [ ] Build frontend assets
- [ ] Configure reverse proxy (Caddy/Nginx)
- [ ] Set up SSL certificates
- [ ] Configure Redis and Celery workers
- [ ] Test all API endpoints
- [ ] Verify WordPress integration works

### Size Estimation

**Backend Package:** ~5-10 MB (excluding virtual environment and dependencies)
**Frontend Package:** ~2-5 MB (excluding node_modules)
**Total Application Code:** ~7-15 MB

**After Installation:**
- Backend with dependencies: ~200-300 MB
- Frontend with dependencies: ~300-500 MB
- Total deployed: ~500-800 MB

---

## 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`.