Files

IGNY8 VPS (Salman) 39df00e5ae 8 Phases refactor

2025-12-03 16:08:02 +00:00

79 KiB

Raw Blame History

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.

System Overview
Architecture
Backend Deep Dive
Frontend Deep Dive
WordPress Plugin Deep Dive
Integration Architecture
AI Framework
Data Models
API Reference
Workflows
Developer Navigation Map
Troubleshooting Map

System Overview

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

IGNY8 SaaS Application - Multi-tenant Django + React application
WordPress Bridge Plugin - Bidirectional sync between WordPress and IGNY8
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
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           │
│  • 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
│   │   │
│   │   ├── 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
│   │   ├── 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.

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.

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, Publisher, Automation, Integration modules

Middleware Stack

RequestIDMiddleware - Assigns unique ID to each request
AccountContextMiddleware - Sets request.account from JWT token
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)

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)

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)

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

IGNY8 → WP (Content Publishing)

IGNY8 creates content via AI Writer
IGNY8 sends POST to /wp-json/igny8/v1/posts/
Plugin validates API key
Create WP post with content
Store _igny8_task_id and _igny8_content_id meta
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:

Plugin stores API key in WP options (igny8_api_key)
All API requests include X-IGNY8-API-Key header
Backend validates key against Site.wp_api_key field
Backend sets account context from API key

Backend → Plugin:

Backend sends requests to WP REST endpoints
Includes X-IGNY8-API-Key header
Plugin validates key matches stored value
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:

Load keywords from database
Build prompt with keyword list
Call AI to group semantically similar keywords
Parse JSON response
Create Cluster records
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:

Load clusters and keywords
Build prompt for content ideation
Call AI to generate ideas
Parse response
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:

Load tasks and content ideas
Build detailed prompt with brief
Call AI to generate article
Parse HTML content
Create/update Content records
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:

Load tasks with image prompts
For each prompt, call image API
Upload images to storage
Create Image records
Link images to content

Data Models

Account & Auth Models

Account (auth/models.py)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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:

{
  "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:

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

Authentication

Login:

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:

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)

"I need to..."

Add a new API endpoint

Create method in ViewSet (modules/[module]/views.py)
Use @action decorator for custom endpoints
Add route to urls.py if needed
Return success_response() or error_response()

Add a new model field

Edit model in business/[domain]/models.py
Run python manage.py makemigrations
Run python manage.py migrate
Update serializers in modules/[module]/serializers.py

Add AI functionality

Create function class in ai/functions/[name].py
Inherit from BaseAIFunction
Implement validate(), prepare(), execute(), save()
Register in ai/registry.py
Call via run_ai_task() from ViewSet

Debug API call

Check request ID in response
Search logs: grep {request_id} logs/
Check middleware: RequestIDMiddleware
Check account context: AccountContextMiddleware

Add WordPress sync logic

Add hook in sync/hooks.php
Implement handler in sync/post-sync.php or sync/taxonomy-sync.php
Use Igny8API class for API calls
Update post meta with _igny8_* keys

Add frontend page

Create component in frontend/src/pages/[Module]/[Page].tsx
Add route in App.tsx
Add to sidebar navigation in layout/Sidebar.tsx
Create API calls in api/[module].ts
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

# 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

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

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

79 KiB Raw Blame History

IGNY8 System Master Reference

Table of Contents

System Overview

Core Capabilities

Architecture

High-Level System Architecture

Data Hierarchy

Backend Deep Dive

Technology Stack

Project Structure

Core Base Classes

AccountModelViewSet

SiteSectorModelViewSet

Middleware Stack

Frontend Deep Dive

Technology Stack

Project Structure

State Management (Zustand)

WordPress Plugin Deep Dive

Plugin Structure

Core Classes

Igny8API

Igny8RestAPI

Igny8Site

Sync Flow

WP → IGNY8 (Post Status Updates)

IGNY8 → WP (Content Publishing)

Post Meta Fields

Integration Architecture

WordPress ↔ IGNY8 Integration

Authentication Flow

AI Framework

Architecture

AI Functions

auto_cluster

generate_ideas

generate_content

generate_images

Data Models

Account & Auth Models

Planner Models

Writer Models

Integration Models

API Reference

Base URL

Unified Response Format

Authentication

Key Endpoints by Module

Planner Module

Writer Module

Integration Module

System Module

Billing Module

Workflows

1. Keyword to Published Post (Full Workflow)

2. WordPress Integration Setup

Developer Navigation Map

"I need to..."

Add a new API endpoint

Add a new model field

Add AI functionality

Debug API call

Add WordPress sync logic

Add frontend page

Troubleshooting Map

Common Issues and Where to Look

"Authentication failed / 401 errors"

"Posts not syncing to IGNY8"

"AI task stuck/failed"

"Frontend can't fetch data"

"WordPress plugin can't connect"

"Rate limiting errors"

"Account isolation not working"

File Quick Reference

Most Important Files

Technology Dependencies

Backend

Frontend

WordPress Plugin

79 KiB

Raw Blame History