From d412651875496cdbeb2bbacfea32145cbd10d371 Mon Sep 17 00:00:00 2001 From: "IGNY8 VPS (Salman)" Date: Sat, 29 Nov 2025 16:34:31 +0000 Subject: [PATCH] stb --- docs/MASTER_REFERENCE.md | 2138 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 2138 insertions(+) create mode 100644 docs/MASTER_REFERENCE.md diff --git a/docs/MASTER_REFERENCE.md b/docs/MASTER_REFERENCE.md new file mode 100644 index 00000000..3d40afaf --- /dev/null +++ b/docs/MASTER_REFERENCE.md @@ -0,0 +1,2138 @@ +# 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; + logout: () => void; + refreshAccessToken: () => Promise; +} +``` + +**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= +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 + +--- + +## Folder Status Analysis + +### Active Folders + +#### `/sites/` - **ACTIVE & IN USE** ✅ +**Status:** Currently deployed and running in production +**Container:** `igny8_sites` (running on port 8024) +**Purpose:** Unified Sites Renderer and Site Builder container + +**Evidence:** +- Docker container running: `igny8_sites` (Up 6+ hours) +- Referenced in `docker-compose.app.yml` (lines 104-123) +- Active backend integration via `/api/v1/publisher/sites/{site_id}/definition/` +- Loads site definitions from `/data/app/sites-data/` filesystem +- Has complete React application with routing, components, and build configuration + +**Functionality:** +1. **Public Site Renderer** (No auth required) + - Routes: `/:siteSlug/:pageSlug?` + - Loads site definitions from filesystem or API + - Renders published sites for public viewing + +2. **Site Builder Interface** (Auth required) + - Routes: `/builder/*` (wizard, preview, dashboard) + - Protected by JWT authentication + - Integrated with main IGNY8 API + +**Migration History:** +- Previously separated into two containers (`site-builder` + `sites`) +- Successfully merged in November 2025 (see `MIGRATION_SUMMARY.md`) +- Old `site-builder` container removed, functionality merged into `sites` + +**Key Files:** +``` +sites/ +├── package.json ✅ Active (vite 7.2.2, react 19.2.0) +├── Dockerfile.dev ✅ Active (used by docker-compose) +├── vite.config.ts ✅ Active (port 5176) +└── src/ + ├── App.tsx ✅ Unified router (builder + renderer) + ├── builder/ ✅ Site builder UI (lazy loaded) + │ ├── pages/ + │ └── components/ + ├── pages/ + │ └── SiteRenderer.tsx ✅ Public site renderer + └── loaders/ + └── loadSiteDefinition.ts ✅ Filesystem/API loader +``` + +**Backend Integration:** +- API: `/api/v1/site-builder/blueprints/` (active, 20+ endpoints) +- Service: `igny8_core.business.publishing.services.adapters.sites_renderer_adapter` +- Data path: `/data/app/sites-data/clients/{site_id}/v{version}/` + +**Verdict:** **ESSENTIAL - Must be included in portable package** + +--- + +#### `/site-builder/` - **REDUNDANT & DEPRECATED** ❌ +**Status:** Empty folder, functionality migrated to `/sites/` +**Last Active:** Before November 2025 +**Container:** None (removed from docker-compose) + +**Evidence:** +- Folder contains only: `dist/` and `node_modules/` (no source code) +- No `.tsx`, `.ts`, or configuration files found +- Removed from `docker-compose.app.yml` (commented out) +- Migration documented in `/sites/MIGRATION_SUMMARY.md` + +**Migration History:** +According to `MIGRATION_SUMMARY.md`: +- Site Builder functionality merged into `/sites/src/builder/` directory +- Unified routing created in `/sites/src/App.tsx` +- Docker service `igny8_site_builder` removed +- All builder API calls now route through `/sites/` container + +**What Happened:** +``` +Old Structure: New Structure: +/site-builder/ → /sites/src/builder/ + src/ pages/ + pages/ components/ + components/ (integrated into sites) + api/ +``` + +**Verdict:** **REDUNDANT - Can be safely deleted** + +**Cleanup Recommendation:** +```bash +# Safe to remove (after final verification) +rm -rf /data/app/igny8/site-builder/ +``` + +--- + +### Frontend Module Analysis + +#### `/frontend/src/modules/siteBuilder/` - **REDUNDANT & DEPRECATED** ❌ +**Status:** Empty folders, no active code +**Structure:** +``` +frontend/src/modules/siteBuilder/ +├── components/ +│ ├── common/ (empty) +│ └── steps/ (empty) +└── state/ (empty) +``` + +**Evidence:** +- No `.tsx` or `.ts` files found in directory tree +- No imports reference this path (`grep` search returned 0 matches) +- Site Builder functionality moved to `/sites/src/builder/` + +**Verdict:** **REDUNDANT - Can be safely deleted** + +**Cleanup Recommendation:** +```bash +# Safe to remove +rm -rf /data/app/igny8/frontend/src/modules/siteBuilder/ +``` + +--- + +### Updated Portable Package Structure + +Based on analysis, here's the corrected essential package: + +#### Include These Folders: +✅ `/backend/` - Main Django application (excluding venv, cache, logs) +✅ `/frontend/` - Main React application (excluding node_modules, dist) +✅ `/sites/` - **ACTIVE** Sites Renderer & Builder (excluding node_modules, dist) +✅ `/docs/` - Documentation +✅ `docker-compose.app.yml` - Deployment configuration +✅ `README.md`, `CHANGELOG.md` - Project documentation + +#### Exclude These Folders: +❌ `/site-builder/` - **DEPRECATED** (empty, migrated to `/sites/`) +❌ `/frontend/src/modules/siteBuilder/` - **DEPRECATED** (empty folders) +❌ `node_modules/`, `dist/`, `.venv/` - Dependencies (installed on deployment) +❌ `__pycache__/`, `*.pyc` - Compiled Python +❌ `logs/`, `*.log` - Log files +❌ Database files, backups - Environment-specific + +--- + +## 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`.