From d7a49525f466469084e19bb01a47714cc69974ce Mon Sep 17 00:00:00 2001 From: alorig <220087330+alorig@users.noreply.github.com> Date: Sat, 29 Nov 2025 21:46:27 +0500 Subject: [PATCH] 12 --- docs/MASTER_REFERENCE.md | 1992 ----------------- ...00-SYSTEM-ARCHITECTURE-MASTER-REFERENCE.md | 0 .../SITES_DECISION_GUIDE.md | 0 .../SITES_REMOVAL_GUIDE.md | 0 .../SITES_REMOVAL_QUICK_REFERENCE.md | 0 5 files changed, 1992 deletions(-) delete mode 100644 docs/MASTER_REFERENCE.md rename docs/{ => future-plan-to-remove-sites-site-builder-wrong-plan}/00-SYSTEM-ARCHITECTURE-MASTER-REFERENCE.md (100%) rename docs/{ => future-plan-to-remove-sites-site-builder-wrong-plan}/SITES_DECISION_GUIDE.md (100%) rename docs/{ => future-plan-to-remove-sites-site-builder-wrong-plan}/SITES_REMOVAL_GUIDE.md (100%) rename docs/{ => future-plan-to-remove-sites-site-builder-wrong-plan}/SITES_REMOVAL_QUICK_REFERENCE.md (100%) diff --git a/docs/MASTER_REFERENCE.md b/docs/MASTER_REFERENCE.md deleted file mode 100644 index 66726ce2..00000000 --- a/docs/MASTER_REFERENCE.md +++ /dev/null @@ -1,1992 +0,0 @@ -# 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 - ---- - -## 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`. diff --git a/docs/00-SYSTEM-ARCHITECTURE-MASTER-REFERENCE.md b/docs/future-plan-to-remove-sites-site-builder-wrong-plan/00-SYSTEM-ARCHITECTURE-MASTER-REFERENCE.md similarity index 100% rename from docs/00-SYSTEM-ARCHITECTURE-MASTER-REFERENCE.md rename to docs/future-plan-to-remove-sites-site-builder-wrong-plan/00-SYSTEM-ARCHITECTURE-MASTER-REFERENCE.md diff --git a/docs/SITES_DECISION_GUIDE.md b/docs/future-plan-to-remove-sites-site-builder-wrong-plan/SITES_DECISION_GUIDE.md similarity index 100% rename from docs/SITES_DECISION_GUIDE.md rename to docs/future-plan-to-remove-sites-site-builder-wrong-plan/SITES_DECISION_GUIDE.md diff --git a/docs/SITES_REMOVAL_GUIDE.md b/docs/future-plan-to-remove-sites-site-builder-wrong-plan/SITES_REMOVAL_GUIDE.md similarity index 100% rename from docs/SITES_REMOVAL_GUIDE.md rename to docs/future-plan-to-remove-sites-site-builder-wrong-plan/SITES_REMOVAL_GUIDE.md diff --git a/docs/SITES_REMOVAL_QUICK_REFERENCE.md b/docs/future-plan-to-remove-sites-site-builder-wrong-plan/SITES_REMOVAL_QUICK_REFERENCE.md similarity index 100% rename from docs/SITES_REMOVAL_QUICK_REFERENCE.md rename to docs/future-plan-to-remove-sites-site-builder-wrong-plan/SITES_REMOVAL_QUICK_REFERENCE.md