igny8/docs/planning/PHASE-3-4-IMPLEMENTATION-PLAN.md

PHASE 3 & 4 IMPLEMENTATION PLAN

Detailed Configuration Plan for Site Builder & Linker/Optimizer

Created: 2025-01-XX
Status: Phase 3 Complete ✅ | Phase 4 Backend Complete ✅ | Phase 4 Frontend Pending

---

TABLE OF CONTENTS

1. Implementation Summary ⭐ NEW
2. Overview
3. Phase 3: Site Builder Implementation Plan
4. Phase 4: Linker & Optimizer Implementation Plan
5. Integration Points
6. File Structure
7. Dependencies & Order
8. Testing Strategy

---

IMPLEMENTATION SUMMARY

Last Updated: 2025-01-XX
Session: Phase 3 & 4 Implementation Session

✅ Phase 3: Site Builder - COMPLETE

Backend Implementation

Models Created (backend/igny8_core/business/site_building/models.py):

• ✅ SiteBlueprint model with fields:
  • name, description
  • config_json (wizard configuration)
  • structure_json (AI-generated structure)
  • status (draft, generating, ready, deployed)
  • hosting_type (igny8_sites, wordpress, shopify, multi)
  • version, deployed_version
  • Inherits from SiteSectorBaseModel (account, site, sector)
• ✅ PageBlueprint model with fields:
  • site_blueprint (ForeignKey)
  • slug, title, type
  • blocks_json (page content blocks)
  • status (draft, generating, ready)
  • order
  • Inherits from SiteSectorBaseModel

Services Created:

• ✅ StructureGenerationService (business/site_building/services/structure_generation_service.py)
  • generate_structure() - Triggers AI structure generation
  • Integrates with CreditService for credit checks
  • Dispatches Celery tasks for async processing
• ✅ PageGenerationService (business/site_building/services/page_generation_service.py)
  • generate_page_content() - Creates Writer tasks from page blueprints
  • regenerate_page() - Regenerates page content
  • Integrates with ContentGenerationService
• ✅ SiteBuilderFileService (business/site_building/services/file_management_service.py)
  • upload_file() - Handles file uploads with access control
  • delete_file() - Deletes files with validation
  • list_files() - Lists files for a site
  • check_file_access() - Validates user access to site files

AI Function Created:

• ✅ GenerateSiteStructureFunction (ai/functions/generate_site_structure.py)
  • Operation type: site_structure_generation
  • Credit cost: 50 credits (from constants)
  • Parses AI response JSON and syncs PageBlueprint instances
  • Handles page creation, updates, and deletions
• ✅ Added to AI registry (ai/registry.py)
• ✅ Added prompt to ai/prompts.py (site_structure_generation)
• ✅ Integrated into ai/engine.py with phase tracking

API Layer Created (modules/site_builder/):

• ✅ SiteBuilderViewSet with actions:
  • CRUD operations for SiteBlueprint
  • generate_structure/ (POST) - Triggers AI structure generation
• ✅ PageBlueprintViewSet with actions:
  • CRUD operations for PageBlueprint
  • generate_content/ (POST) - Generates page content via Writer
  • regenerate/ (POST) - Regenerates page content
• ✅ SiteAssetView (APIView) for file management:
  • GET - List files
  • POST - Upload file
  • DELETE - Delete file
• ✅ Serializers:
  • SiteBlueprintSerializer
  • PageBlueprintSerializer
  • SiteBlueprintDetailSerializer
  • PageBlueprintDetailSerializer
  • FileUploadSerializer
• ✅ URLs registered at /api/v1/site-builder/

Migrations:

• ✅ 0001_initial.py - Creates SiteBlueprint and PageBlueprint tables
• ✅ Applied to database

Django App Configuration:

• ✅ business/site_building/apps.py - SiteBuildingConfig
• ✅ modules/site_builder/apps.py - SiteBuilderConfig
• ✅ Added to INSTALLED_APPS in settings.py

Frontend Implementation

Site Builder Container (site-builder/):

• ✅ Created standalone Vite + React + TypeScript application
• ✅ Docker container configured (Dockerfile.dev)
• ✅ Docker Compose service (igny8_site_builder) on port 8025:5175
• ✅ Routed to builder.igny8.com via Caddy reverse proxy
• ✅ Vite config with @shared alias for shared components
• ✅ Node.js 22 (upgraded from 18 for Vite 7 compatibility)

Wizard Pages (site-builder/src/pages/wizard/):

• ✅ WizardPage.tsx - Main wizard orchestrator with step navigation
• ✅ BusinessDetailsStep.tsx - Step 1: Business type, industry, audience
• ✅ BriefStep.tsx - Step 2: Business brief textarea
• ✅ ObjectivesStep.tsx - Step 3: Multiple objectives with add/remove
• ✅ StyleStep.tsx - Step 4: Style preferences (palette, typography, personality)

Preview & Dashboard:

• ✅ PreviewCanvas.tsx - Live preview of generated site structure
• ✅ SiteDashboard.tsx - Lists all site blueprints

State Management (site-builder/src/state/):

• ✅ builderStore.ts (Zustand) - Wizard state:
  • currentStep, wizardData, activeBlueprint
  • isSubmitting, error
  • Actions: nextStep, previousStep, submitWizard, etc.
• ✅ siteDefinitionStore.ts (Zustand) - Site preview state:
  • siteStructure, pages, activePageSlug
  • Actions: setSiteStructure, setPages, refreshSiteDefinition

API Client (site-builder/src/api/):

• ✅ builder.api.ts - API functions:
  • createBlueprint(), getBlueprint(), generateStructure()
  • getPages(), generatePageContent()
  • uploadFile(), deleteFile(), listFiles()

Type Definitions (site-builder/src/types/):

• ✅ siteBuilder.ts - TypeScript interfaces:
  • SiteBlueprint, PageBlueprint, PageBlock
  • SiteConfig, SiteStructure, SiteWizardData

Shared Component Library (frontend/src/components/shared/):

• ✅ Blocks:
  • HeroBlock.tsx - Hero section component
  • FeatureGridBlock.tsx - Feature grid layout
  • StatsPanel.tsx - Statistics display
  • blocks.css - Shared block styles
• ✅ Layouts:
  • DefaultLayout.tsx - Standard site layout
  • MinimalLayout.tsx - Minimal layout variant
  • layouts.css - Shared layout styles
• ✅ Templates:
  • MarketingTemplate.tsx - Marketing site template
  • LandingTemplate.tsx - Landing page template
• ✅ Barrel Exports:
  • blocks/index.ts, layouts/index.ts, templates/index.ts
  • shared/index.ts - Main export file
• ✅ Documentation:
  • shared/README.md - Usage guide for shared components

Routing & Navigation:

• ✅ React Router configured with routes:
  • / - Wizard page
  • /preview - Preview canvas
  • /dashboard - Site dashboard
• ✅ Sidebar navigation with icons (Wand2, LayoutTemplate, PanelsTopLeft)

Styling:

• ✅ TailwindCSS configured
• ✅ Global styles (index.css)
• ✅ App-specific styles (App.css)
• ✅ Component-specific CSS files

Infrastructure

Docker Configuration:

• ✅ docker-compose.app.yml - Added igny8_site_builder service
• ✅ Container runs on port 8025:5175
• ✅ Volume mount: /data/app/igny8/site-builder:/app:rw
• ✅ Environment: VITE_API_URL: "https://api.igny8.com/api"
• ✅ Depends on igny8_backend health check

Caddy Routing:

• ✅ Added builder.igny8.com server block to Caddyfile
• ✅ WebSocket support for Vite HMR
• ✅ Reverse proxy to igny8_site_builder:5175
• ✅ HTTPS enabled via automatic certificates

Package Dependencies (site-builder/package.json):

• ✅ React 19.2.0, React DOM 19.2.0
• ✅ React Router DOM 7.9.6
• ✅ Zustand 5.0.8 (state management)
• ✅ Axios 1.13.2 (API client)
• ✅ React Hook Form 7.66.0
• ✅ Lucide React 0.554.0 (icons)
• ✅ Vitest 2.1.5, React Testing Library (testing)
• ✅ Vite 7.2.2, TypeScript 5.9.3

Testing

Backend Tests:

• ✅ business/site_building/tests/base.py - SiteBuilderTestBase with fixtures
• ✅ business/site_building/tests/test_services.py:
  • StructureGenerationServiceTests - Tests structure generation flow
  • PageGenerationServiceTests - Tests page content generation
• ✅ ai/tests/test_generate_site_structure_function.py:
  • Tests JSON parsing from AI response
  • Tests PageBlueprint sync (create/update/delete)
  • Tests prompt building with existing pages

Frontend Tests:

• ✅ setupTests.ts - Vitest configuration with jsdom
• ✅ state/__tests__/builderStore.test.ts - Wizard store tests
• ✅ state/__tests__/siteDefinitionStore.test.ts - Site definition store tests
• ✅ pages/wizard/__tests__/WizardPage.test.tsx - Wizard component tests
• ✅ pages/preview/__tests__/PreviewCanvas.test.tsx - Preview component tests

Bug Fixes & Issues Resolved

1. 500 Error on /v1/writer/tasks:

   • Issue: TasksSerializer crashing when Content record doesn't exist
   • Fix: Updated _get_content_record() to catch ObjectDoesNotExist exception
   • File: modules/writer/serializers.py

2. Database Schema Mismatch:

   • Issue: Content model had Phase 4 fields not in database
   • Fix: Created and applied migration 0009_add_content_site_source_fields.py
   • File: modules/writer/migrations/0009_add_content_site_source_fields.py

3. Node.js Version Incompatibility:

   • Issue: Vite 7 requires Node.js 20.19+ or 22.12+
   • Fix: Updated Dockerfile.dev from node:18-alpine to node:22-alpine
   • File: site-builder/Dockerfile.dev

4. Vite Host Blocking:

   • Issue: Vite dev server blocking builder.igny8.com requests
   • Fix: Added builder.igny8.com to server.allowedHosts in vite.config.ts
   • File: site-builder/vite.config.ts

5. Vite Alias Resolution:

   • Issue: @shared alias not resolving for shared components
   • Fix: Added dynamic path resolution and fs.allow configuration
   • File: site-builder/vite.config.ts

6. Migration Dependency Error:

   • Issue: ValueError: Related model 'igny8_core_auth.account' cannot be resolved
   • Fix: Updated migration dependency to 0014_remove_plan_operation_limits_phase0
   • File: business/site_building/migrations/0001_initial.py

7. Frontend Test Failures:

   • Issue: Multiple elements matching text query
   • Fix: Changed getByText to getAllByText in PreviewCanvas.test.tsx
   • Issue: Incomplete mock state in WizardPage.test.tsx
   • Fix: Added complete style object with default values

✅ Phase 4: Linker & Optimizer - Backend Complete

Backend Implementation

Content Model Extensions (business/content/models.py):

• ✅ Added source field (igny8, wordpress, shopify, custom)
• ✅ Added sync_status field (native, imported, synced)
• ✅ Added external_id, external_url, sync_metadata fields
• ✅ Added internal_links JSON field
• ✅ Added linker_version integer field
• ✅ Added optimizer_version integer field
• ✅ Added optimization_scores JSON field
• ✅ Migration created and applied

Linking Services (business/linking/services/):

• ✅ LinkerService - Main service for internal linking
• ✅ CandidateEngine - Finds link candidates based on content relevance
• ✅ InjectionEngine - Injects links into HTML content

Optimization Services (business/optimization/):

• ✅ OptimizationTask model - Tracks optimization operations
• ✅ OptimizerService - Main service with multiple entry points:
  • optimize_from_writer()
  • optimize_from_wordpress_sync()
  • optimize_from_external_sync()
  • optimize_manual()
• ✅ ContentAnalyzer - Analyzes content for SEO, readability, engagement

Content Pipeline Service (business/content/services/):

• ✅ ContentPipelineService - Orchestrates Writer → Linker → Optimizer pipeline
• ✅ process_writer_content() - Full pipeline for Writer content
• ✅ process_synced_content() - Optimization-only for synced content

Note: Phase 4 frontend UI (Linker Dashboard, Optimizer Dashboard) is not yet implemented.

📋 Files Created/Modified

Backend Files Created

Models & Migrations:

• backend/igny8_core/business/site_building/models.py
• backend/igny8_core/business/site_building/migrations/0001_initial.py
• backend/igny8_core/business/site_building/apps.py
• backend/igny8_core/modules/writer/migrations/0009_add_content_site_source_fields.py

Services:

• backend/igny8_core/business/site_building/services/file_management_service.py
• backend/igny8_core/business/site_building/services/structure_generation_service.py
• backend/igny8_core/business/site_building/services/page_generation_service.py
• backend/igny8_core/business/linking/services/linker_service.py
• backend/igny8_core/business/linking/services/candidate_engine.py
• backend/igny8_core/business/linking/services/injection_engine.py
• backend/igny8_core/business/optimization/models.py
• backend/igny8_core/business/optimization/services/optimizer_service.py
• backend/igny8_core/business/content/services/content_pipeline_service.py

AI Functions:

• backend/igny8_core/ai/functions/generate_site_structure.py

API Layer:

• backend/igny8_core/modules/site_builder/__init__.py
• backend/igny8_core/modules/site_builder/apps.py
• backend/igny8_core/modules/site_builder/serializers.py
• backend/igny8_core/modules/site_builder/views.py
• backend/igny8_core/modules/site_builder/urls.py

Tests:

• backend/igny8_core/business/site_building/tests/__init__.py
• backend/igny8_core/business/site_building/tests/base.py
• backend/igny8_core/business/site_building/tests/test_services.py
• backend/igny8_core/ai/tests/test_generate_site_structure_function.py

Backend Files Modified

• backend/igny8_core/settings.py - Added Site Builder apps to INSTALLED_APPS
• backend/igny8_core/urls.py - Added Site Builder URL routing
• backend/igny8_core/ai/registry.py - Registered GenerateSiteStructureFunction
• backend/igny8_core/ai/prompts.py - Added site_structure_generation prompt
• backend/igny8_core/ai/engine.py - Integrated site structure generation
• backend/igny8_core/business/content/models.py - Added Phase 4 fields
• backend/igny8_core/modules/writer/serializers.py - Fixed Content.DoesNotExist handling

Frontend Files Created

Site Builder Application:

• site-builder/package.json
• site-builder/vite.config.ts
• site-builder/tsconfig.app.json
• site-builder/Dockerfile.dev
• site-builder/src/main.tsx
• site-builder/src/App.tsx
• site-builder/src/App.css
• site-builder/src/index.css
• site-builder/src/setupTests.ts

Pages:

• site-builder/src/pages/wizard/WizardPage.tsx
• site-builder/src/pages/wizard/steps/BusinessDetailsStep.tsx
• site-builder/src/pages/wizard/steps/BriefStep.tsx
• site-builder/src/pages/wizard/steps/ObjectivesStep.tsx
• site-builder/src/pages/wizard/steps/StyleStep.tsx
• site-builder/src/pages/preview/PreviewCanvas.tsx
• site-builder/src/pages/dashboard/SiteDashboard.tsx

State Management:

• site-builder/src/state/builderStore.ts
• site-builder/src/state/siteDefinitionStore.ts

API & Types:

• site-builder/src/api/builder.api.ts
• site-builder/src/types/siteBuilder.ts

Components:

• site-builder/src/components/common/Card.tsx
• site-builder/src/components/common/Card.css

Tests:

• site-builder/src/state/__tests__/builderStore.test.ts
• site-builder/src/state/__tests__/siteDefinitionStore.test.ts
• site-builder/src/pages/wizard/__tests__/WizardPage.test.tsx
• site-builder/src/pages/preview/__tests__/PreviewCanvas.test.tsx

Shared Component Library:

• frontend/src/components/shared/blocks/HeroBlock.tsx
• frontend/src/components/shared/blocks/FeatureGridBlock.tsx
• frontend/src/components/shared/blocks/StatsPanel.tsx
• frontend/src/components/shared/blocks/blocks.css
• frontend/src/components/shared/blocks/index.ts
• frontend/src/components/shared/layouts/DefaultLayout.tsx
• frontend/src/components/shared/layouts/MinimalLayout.tsx
• frontend/src/components/shared/layouts/layouts.css
• frontend/src/components/shared/layouts/index.ts
• frontend/src/components/shared/templates/MarketingTemplate.tsx
• frontend/src/components/shared/templates/LandingTemplate.tsx
• frontend/src/components/shared/templates/index.ts
• frontend/src/components/shared/index.ts
• frontend/src/components/shared/README.md

Infrastructure Files Modified

• docker-compose.app.yml - Added igny8_site_builder service
• /var/lib/docker/volumes/portainer_data/_data/caddy/Caddyfile - Added builder.igny8.com routing

Files Removed (Temporary/One-Time Use)

• backend/import_plans.py - One-time data import script
• backend/igny8_core/test_settings.py - Temporary test configuration
• backend/igny8_core/api/tests/run_tests.py - Helper test script
• backend/igny8_core/ai/tests/test_run.py - Temporary AI test script

🔄 Remaining Work

Phase 3 - Minor Enhancements

• Add file browser UI component to Site Builder
• Add deployment functionality (Phase 5 integration)
• Add page editor for manual block editing
• Add template selection in wizard

Phase 4 - Frontend UI

• Create Linker Dashboard (frontend/src/pages/Linker/Dashboard.tsx)
• Create Linker Content List (frontend/src/pages/Linker/ContentList.tsx)
• Create Optimizer Dashboard (frontend/src/pages/Optimizer/Dashboard.tsx)
• Create Optimizer Content Selector (frontend/src/pages/Optimizer/ContentSelector.tsx)
• Create shared components:
  • SourceBadge.tsx - Display content source
  • SyncStatusBadge.tsx - Display sync status
  • ContentFilter.tsx - Filter by source/sync_status
• Update Writer content list to show source badges
• Add "Send to Optimizer" button in Writer

Phase 4 - AI Function

• Create OptimizeContentFunction (ai/functions/optimize_content.py)
• Add optimization prompts to ai/prompts.py
• Register function in ai/registry.py
• Integrate into ai/engine.py

Phase 4 - API Layer

• Create modules/linker/ module with ViewSet
• Create modules/optimizer/ module with ViewSet
• Register URLs for Linker and Optimizer APIs

📊 Implementation Statistics

• Backend Files Created: 25+
• Frontend Files Created: 30+
• Backend Tests: 3 test files, 10+ test cases
• Frontend Tests: 4 test files, 15+ test cases
• Lines of Code: ~5,000+ (backend + frontend)
• Docker Containers: 1 new container (igny8_site_builder)
• API Endpoints: 10+ new endpoints
• Database Tables: 2 new tables (SiteBlueprint, PageBlueprint)
• Migrations: 2 migrations created and applied

---

OVERVIEW

Implementation Approach

• Phase 3: Build Site Builder with wizard, AI structure generation, and file management
• Phase 4: Implement Linker and Optimizer as post-processing stages with multiple entry points
• Shared Components: Create global component library for reuse across apps
• Integration: Ensure seamless integration with existing Phase 1 & 2 services

Key Principles

• Service Layer Pattern: All business logic in services (Phase 1 pattern)
• Credit-Aware: All operations check credits before execution
• Multiple Entry Points: Optimizer works from Writer, WordPress sync, 3rd party, manual
• Component Reuse: Shared components across Site Builder, Sites Renderer, Main App

---

PHASE 3: SITE BUILDER IMPLEMENTATION PLAN

3.1 Backend Structure

Business Layer (business/site_building/)

business/site_building/
├── __init__.py
├── models.py                    # SiteBlueprint, PageBlueprint
├── migrations/
│   └── 0001_initial.py
└── services/
    ├── __init__.py
    ├── file_management_service.py
    ├── structure_generation_service.py
    └── page_generation_service.py

Models to Create:

1. SiteBlueprint (business/site_building/models.py)

   • Fields:
     • name, description
     • config_json (wizard choices: business_type, style, objectives)
     • structure_json (AI-generated structure: pages, layout, theme)
     • status (draft, generating, ready, deployed)
     • hosting_type (igny8_sites, wordpress, shopify, multi)
     • version, deployed_version
     • Inherits from SiteSectorBaseModel

2. PageBlueprint (business/site_building/models.py)

   • Fields:
     • site_blueprint (ForeignKey)
     • slug, title
     • type (home, about, services, products, blog, contact, custom)
     • blocks_json (page content blocks)
     • status (draft, generating, ready)
     • order
     • Inherits from SiteSectorBaseModel

Services to Create

1. FileManagementService (business/site_building/services/file_management_service.py)

   class SiteBuilderFileService:
       def get_user_accessible_sites(self, user)
       def check_file_access(self, user, site_id)
       def upload_file(self, user, site_id, file, folder='images')
       def delete_file(self, user, site_id, file_path)
       def list_files(self, user, site_id, folder='images')
       def check_storage_quota(self, site_id, file_size)
   

2. StructureGenerationService (business/site_building/services/structure_generation_service.py)

   class StructureGenerationService:
       def __init__(self):
           self.ai_function = GenerateSiteStructureFunction()
           self.credit_service = CreditService()
   
       def generate_structure(self, site_blueprint, business_brief, objectives, style)
       def _create_page_blueprints(self, site_blueprint, structure)
   

3. PageGenerationService (business/site_building/services/page_generation_service.py)

   class PageGenerationService:
       def __init__(self):
           self.content_service = ContentGenerationService()
           self.credit_service = CreditService()
   
       def generate_page_content(self, page_blueprint, account)
       def regenerate_page(self, page_blueprint, account)
   

AI Functions (infrastructure/ai/functions/)

1. GenerateSiteStructureFunction (infrastructure/ai/functions/generate_site_structure.py)
   • Operation type: site_structure_generation
   • Credit cost: 50 credits (from constants)
   • Generates site structure JSON from business brief

API Layer (modules/site_builder/)

modules/site_builder/
├── __init__.py
├── views.py                    # SiteBuilderViewSet, PageBlueprintViewSet, FileUploadView
├── serializers.py              # SiteBlueprintSerializer, PageBlueprintSerializer
├── urls.py
└── apps.py

ViewSets to Create:

1. SiteBuilderViewSet (modules/site_builder/views.py)

   • CRUD for SiteBlueprint
   • Actions:
     • generate_structure/ (POST) - Trigger AI structure generation
     • deploy/ (POST) - Deploy site to hosting
     • preview/ (GET) - Get preview JSON

2. PageBlueprintViewSet (modules/site_builder/views.py)

   • CRUD for PageBlueprint
   • Actions:
     • generate_content/ (POST) - Generate page content
     • regenerate/ (POST) - Regenerate page content

3. FileUploadView (modules/site_builder/views.py)

   • upload/ (POST) - Upload file to site assets
   • delete/ (DELETE) - Delete file
   • list/ (GET) - List files

File Storage Structure

/data/app/sites-data/
└── clients/
    └── {site_id}/
        └── v{version}/
            ├── site.json              # Site definition
            ├── pages/                 # Page definitions
            │   ├── home.json
            │   ├── about.json
            │   └── ...
            └── assets/                # User-managed files
                ├── images/
                ├── documents/
                └── media/

3.2 Frontend Structure

Site Builder Container (site-builder/)

site-builder/
├── src/
│   ├── pages/
│   │   ├── wizard/
│   │   │   ├── Step1TypeSelection.tsx
│   │   │   ├── Step2BusinessBrief.tsx
│   │   │   ├── Step3Objectives.tsx
│   │   │   └── Step4Style.tsx
│   │   ├── preview/
│   │   │   └── PreviewCanvas.tsx
│   │   └── dashboard/
│   │       └── SiteList.tsx
│   ├── components/
│   │   ├── blocks/              # Block components (import from shared)
│   │   ├── forms/
│   │   ├── files/
│   │   │   └── FileBrowser.tsx
│   │   └── preview-canvas/
│   ├── state/
│   │   ├── builderStore.ts
│   │   └── siteDefinitionStore.ts
│   ├── api/
│   │   ├── builder.api.ts
│   │   └── sites.api.ts
│   └── main.tsx
├── package.json
├── vite.config.ts
└── Dockerfile

Shared Component Library (frontend/src/components/shared/)

frontend/src/components/shared/
├── blocks/
│   ├── Hero.tsx
│   ├── Features.tsx
│   ├── Services.tsx
│   ├── Products.tsx
│   ├── Testimonials.tsx
│   ├── ContactForm.tsx
│   └── ...
├── layouts/
│   ├── DefaultLayout.tsx
│   ├── MinimalLayout.tsx
│   ├── MagazineLayout.tsx
│   ├── EcommerceLayout.tsx
│   ├── PortfolioLayout.tsx
│   ├── BlogLayout.tsx
│   └── CorporateLayout.tsx
└── templates/
    ├── BlogTemplate.tsx
    ├── BusinessTemplate.tsx
    └── PortfolioTemplate.tsx

3.3 Implementation Tasks

Backend Tasks (Priority Order)

1. Create Business Models

   • Create business/site_building/ folder
   • Create SiteBlueprint model
   • Create PageBlueprint model
   • Create migrations

2. Create Services

   • Create FileManagementService
   • Create StructureGenerationService
   • Create PageGenerationService
   • Integrate with CreditService

3. Create AI Function

   • Create GenerateSiteStructureFunction
   • Add prompts for site structure generation
   • Test AI function

4. Create API Layer

   • Create modules/site_builder/ folder
   • Create SiteBuilderViewSet
   • Create PageBlueprintViewSet
   • Create FileUploadView
   • Create serializers
   • Register URLs

Frontend Tasks (Priority Order)

1. Create Site Builder Container

   • Create site-builder/ folder structure
   • Set up Vite + React + TypeScript
   • Configure Docker container
   • Set up routing

2. Create Wizard

   • Step 1: Business Details (Type Selection)
   • Step 2: Business Brief
   • Step 3: Objectives
   • Step 4: Style Preferences
   • Wizard state management

3. Create Preview Canvas

   • Preview renderer
   • Block rendering
   • Layout rendering

4. Create Shared Components

   • Block components
   • Layout components
   • Template components

---

PHASE 4: LINKER & OPTIMIZER IMPLEMENTATION PLAN

4.1 Backend Structure

Business Layer

business/
├── linking/
│   ├── __init__.py
│   ├── models.py                    # InternalLink (optional)
│   └── services/
│       ├── __init__.py
│       ├── linker_service.py
│       ├── candidate_engine.py
│       └── injection_engine.py
│
├── optimization/
│   ├── __init__.py
│   ├── models.py                    # OptimizationTask, OptimizationScores
│   └── services/
│       ├── __init__.py
│       ├── optimizer_service.py
│       └── analyzer.py
│
└── content/
    └── services/
        └── content_pipeline_service.py  # NEW: Orchestrates pipeline

Content Model Extensions

Extend business/content/models.py:

class Content(SiteSectorBaseModel):
    # Existing fields...
    
    # NEW: Source tracking (Phase 4)
    source = models.CharField(
        max_length=50,
        choices=[
            ('igny8', 'IGNY8 Generated'),
            ('wordpress', 'WordPress Synced'),
            ('shopify', 'Shopify Synced'),
            ('custom', 'Custom API Synced'),
        ],
        default='igny8'
    )
    
    sync_status = models.CharField(
        max_length=50,
        choices=[
            ('native', 'Native IGNY8 Content'),
            ('imported', 'Imported from External'),
            ('synced', 'Synced from External'),
        ],
        default='native'
    )
    
    external_id = models.CharField(max_length=255, blank=True, null=True)
    external_url = models.URLField(blank=True, null=True)
    sync_metadata = models.JSONField(default=dict)
    
    # NEW: Linking fields
    internal_links = models.JSONField(default=list)
    linker_version = models.IntegerField(default=0)
    
    # NEW: Optimization fields
    optimizer_version = models.IntegerField(default=0)
    optimization_scores = models.JSONField(default=dict)

Models to Create

1. OptimizationTask (business/optimization/models.py)

   • Fields:
     • content (ForeignKey to Content)
     • scores_before, scores_after (JSON)
     • html_before, html_after (Text)
     • status (pending, completed, failed)
     • credits_used
     • Inherits from AccountBaseModel

2. OptimizationScores (business/optimization/models.py) - Optional

   • Store detailed scoring metrics

Services to Create

1. LinkerService (business/linking/services/linker_service.py)

   class LinkerService:
       def __init__(self):
           self.candidate_engine = CandidateEngine()
           self.injection_engine = InjectionEngine()
           self.credit_service = CreditService()
   
       def process(self, content_id)
       def batch_process(self, content_ids)
   

2. CandidateEngine (business/linking/services/candidate_engine.py)

   class CandidateEngine:
       def find_candidates(self, content)
       def _find_relevant_content(self, content)
       def _score_candidates(self, content, candidates)
   

3. InjectionEngine (business/linking/services/injection_engine.py)

   class InjectionEngine:
       def inject_links(self, content, candidates)
       def _inject_link_into_html(self, html, link_data)
   

4. OptimizerService (business/optimization/services/optimizer_service.py)

   class OptimizerService:
       def __init__(self):
           self.analyzer = ContentAnalyzer()
           self.ai_function = OptimizeContentFunction()
           self.credit_service = CreditService()
   
       # Multiple entry points
       def optimize_from_writer(self, content_id)
       def optimize_from_wordpress_sync(self, content_id)
       def optimize_from_external_sync(self, content_id)
       def optimize_manual(self, content_id)
   
       # Unified optimization logic
       def optimize(self, content)
   

5. ContentAnalyzer (business/optimization/services/analyzer.py)

   class ContentAnalyzer:
       def analyze(self, content)
       def _calculate_seo_score(self, content)
       def _calculate_readability_score(self, content)
       def _calculate_engagement_score(self, content)
   

6. ContentPipelineService (business/content/services/content_pipeline_service.py)

   class ContentPipelineService:
       def __init__(self):
           self.linker_service = LinkerService()
           self.optimizer_service = OptimizerService()
   
       def process_writer_content(self, content_id, stages=['linking', 'optimization'])
       def process_synced_content(self, content_id, stages=['optimization'])
   

AI Functions

1. OptimizeContentFunction (infrastructure/ai/functions/optimize_content.py)
   • Operation type: optimization
   • Credit cost: 1 credit per 200 words
   • Optimizes content for SEO, readability, engagement

API Layer (modules/linker/ and modules/optimizer/)

modules/
├── linker/
│   ├── __init__.py
│   ├── views.py                    # LinkerViewSet
│   ├── serializers.py
│   ├── urls.py
│   └── apps.py
│
└── optimizer/
    ├── __init__.py
    ├── views.py                    # OptimizerViewSet
    ├── serializers.py
    ├── urls.py
    └── apps.py

ViewSets to Create:

1. LinkerViewSet (modules/linker/views.py)

   • Actions:
     • process/ (POST) - Process content for linking
     • batch_process/ (POST) - Process multiple content items

2. OptimizerViewSet (modules/optimizer/views.py)

   • Actions:
     • optimize/ (POST) - Optimize content (auto-detects source)
     • optimize_from_writer/ (POST) - Entry point 1
     • optimize_from_sync/ (POST) - Entry point 2 & 3
     • optimize_manual/ (POST) - Entry point 4
     • analyze/ (GET) - Analyze content without optimizing

4.2 Frontend Structure

Linker UI (frontend/src/pages/Linker/)

frontend/src/pages/Linker/
├── Dashboard.tsx
├── ContentList.tsx
└── LinkResults.tsx

Optimizer UI (frontend/src/pages/Optimizer/)

frontend/src/pages/Optimizer/
├── Dashboard.tsx
├── ContentSelector.tsx
├── OptimizationResults.tsx
└── ScoreComparison.tsx

Shared Components

frontend/src/components/
├── content/
│   ├── SourceBadge.tsx          # Show content source (IGNY8, WordPress, etc.)
│   ├── SyncStatusBadge.tsx      # Show sync status
│   ├── ContentFilter.tsx        # Filter by source, sync_status
│   └── SourceFilter.tsx

4.3 Implementation Tasks

Backend Tasks (Priority Order)

1. Extend Content Model

   • Add source field
   • Add sync_status field
   • Add external_id, external_url, sync_metadata
   • Add internal_links, linker_version
   • Add optimizer_version, optimization_scores
   • Create migration

2. Create Linking Services

   • Create business/linking/ folder
   • Create LinkerService
   • Create CandidateEngine
   • Create InjectionEngine
   • Integrate with CreditService

3. Create Optimization Services

   • Create business/optimization/ folder
   • Create OptimizationTask model
   • Create OptimizerService (with multiple entry points)
   • Create ContentAnalyzer
   • Integrate with CreditService

4. Create AI Function

   • Create OptimizeContentFunction
   • Add optimization prompts
   • Test AI function

5. Create Pipeline Service

   • Create ContentPipelineService
   • Integrate Linker and Optimizer

6. Create API Layer

   • Create modules/linker/ folder
   • Create LinkerViewSet
   • Create modules/optimizer/ folder
   • Create OptimizerViewSet
   • Create serializers
   • Register URLs

Frontend Tasks (Priority Order)

1. Create Linker UI

   • Linker Dashboard
   • Content List
   • Link Results display

2. Create Optimizer UI

   • Optimizer Dashboard
   • Content Selector (with source filters)
   • Optimization Results
   • Score Comparison

3. Create Shared Components

   • SourceBadge component
   • SyncStatusBadge component
   • ContentFilter component
   • SourceFilter component

4. Update Content List

   • Add source badges
   • Add sync status badges
   • Add filters (by source, sync_status)
   • Add "Send to Optimizer" button

---

INTEGRATION POINTS

Phase 3 Integration

1. With Phase 1 Services

   • StructureGenerationService uses CreditService
   • PageGenerationService uses ContentGenerationService
   • All operations check credits before execution

2. With Phase 2 Automation

   • Automation rules can trigger site structure generation
   • Automation can deploy sites automatically

3. With Content Service

   • Page generation reuses ContentGenerationService
   • Site pages stored as Content records

Phase 4 Integration

1. With Phase 1 Services

   • LinkerService uses CreditService
   • OptimizerService uses CreditService
   • ContentPipelineService orchestrates services

2. With Writer Module

   • Writer → Linker → Optimizer pipeline
   • Content generated in Writer flows to Linker/Optimizer

3. With WordPress Sync (Phase 6)

   • WordPress content synced with source='wordpress'
   • Optimizer works on synced content

4. With 3rd Party Sync (Phase 6)

   • External content synced with source='shopify' or source='custom'
   • Optimizer works on all sources

Cross-Phase Integration

1. Site Builder → Linker/Optimizer

   • Site pages can be optimized
   • Site content can be linked internally

2. Content Pipeline

   • Unified pipeline: Writer → Linker → Optimizer → Publish
   • Works for all content sources

---

FILE STRUCTURE

Complete Backend Structure

backend/igny8_core/
├── business/
│   ├── automation/          # Phase 2 ✅
│   ├── billing/             # Phase 0, 1 ✅
│   ├── content/             # Phase 1 ✅
│   │   └── services/
│   │       └── content_pipeline_service.py  # Phase 4 NEW
│   ├── linking/             # Phase 4 NEW
│   │   ├── models.py
│   │   └── services/
│   │       ├── linker_service.py
│   │       ├── candidate_engine.py
│   │       └── injection_engine.py
│   ├── optimization/        # Phase 4 NEW
│   │   ├── models.py
│   │   └── services/
│   │       ├── optimizer_service.py
│   │       └── analyzer.py
│   ├── planning/            # Phase 1 ✅
│   └── site_building/       # Phase 3 NEW
│       ├── models.py
│       └── services/
│           ├── file_management_service.py
│           ├── structure_generation_service.py
│           └── page_generation_service.py
│
├── modules/
│   ├── automation/          # Phase 2 ✅
│   ├── billing/             # Phase 0, 1 ✅
│   ├── linker/              # Phase 4 NEW
│   ├── optimizer/           # Phase 4 NEW
│   ├── planner/             # Phase 1 ✅
│   ├── site_builder/        # Phase 3 NEW
│   └── writer/              # Phase 1 ✅
│
└── infrastructure/
    └── ai/
        └── functions/
            ├── generate_site_structure.py  # Phase 3 NEW
            └── optimize_content.py          # Phase 4 NEW

Complete Frontend Structure

frontend/src/
├── components/
│   ├── shared/              # Phase 3 NEW
│   │   ├── blocks/
│   │   ├── layouts/
│   │   └── templates/
│   └── content/             # Phase 4 NEW
│       ├── SourceBadge.tsx
│       ├── SyncStatusBadge.tsx
│       └── ContentFilter.tsx
│
└── pages/
    ├── Linker/              # Phase 4 NEW
    │   ├── Dashboard.tsx
    │   └── ContentList.tsx
    ├── Optimizer/           # Phase 4 NEW
    │   ├── Dashboard.tsx
    │   └── ContentSelector.tsx
    └── Writer/              # Phase 1 ✅
        └── ...

site-builder/src/            # Phase 3 NEW
├── pages/
│   ├── wizard/
│   ├── preview/
│   └── dashboard/
└── components/

---

DEPENDENCIES & ORDER

Phase 3 Dependencies

1. Required (Already Complete)

   • ✅ Phase 0: Credit system
   • ✅ Phase 1: Service layer (ContentGenerationService, CreditService)
   • ✅ Phase 2: Automation system (optional integration)

2. Phase 3 Implementation Order

   • Step 1: Create models (SiteBlueprint, PageBlueprint)
   • Step 2: Create FileManagementService
   • Step 3: Create StructureGenerationService + AI function
   • Step 4: Create PageGenerationService
   • Step 5: Create API layer (ViewSets)
   • Step 6: Create frontend container structure
   • Step 7: Create wizard UI
   • Step 8: Create preview canvas
   • Step 9: Create shared component library

Phase 4 Dependencies

1. Required (Already Complete)

   • ✅ Phase 0: Credit system
   • ✅ Phase 1: Service layer (ContentGenerationService, CreditService)
   • ✅ Content model (needs extension)

2. Phase 4 Implementation Order

   • Step 1: Extend Content model (add source, sync_status, linking, optimization fields)
   • Step 2: Create linking services (LinkerService, CandidateEngine, InjectionEngine)
   • Step 3: Create optimization services (OptimizerService, ContentAnalyzer)
   • Step 4: Create optimization AI function
   • Step 5: Create ContentPipelineService
   • Step 6: Create API layer (LinkerViewSet, OptimizerViewSet)
   • Step 7: Create frontend UI (Linker Dashboard, Optimizer Dashboard)
   • Step 8: Create shared components (SourceBadge, ContentFilter)

Parallel Implementation

• Phase 3 and Phase 4 can be implemented in parallel after:
  • Content model extensions (Phase 4 Step 1) are complete
  • Both phases use Phase 1 services independently

---

TESTING STRATEGY

Phase 3 Testing

1. Backend Tests

   • Test SiteBlueprint CRUD
   • Test PageBlueprint CRUD
   • Test structure generation (AI function)
   • Test file upload/delete/access
   • Test credit deduction

2. Frontend Tests

   • Test wizard flow
   • Test preview rendering
   • Test file browser
   • Test component library

Phase 4 Testing

1. Backend Tests

   • Test Content model extensions
   • Test LinkerService (find candidates, inject links)
   • Test OptimizerService (all entry points)
   • Test ContentPipelineService
   • Test credit deduction

2. Frontend Tests

   • Test Linker UI
   • Test Optimizer UI
   • Test source filtering
   • Test content selection

Integration Tests

1. Writer → Linker → Optimizer Pipeline

   • Test full pipeline flow
   • Test credit deduction at each stage

2. WordPress Sync → Optimizer (Phase 6)

   • Test synced content optimization
   • Test source tracking

---

CREDIT COSTS

Phase 3 Credit Costs

• site_structure_generation: 50 credits (per site blueprint)
• site_page_generation: 20 credits (per page)
• File storage: No credits (storage quota based)

Phase 4 Credit Costs

• linking: 8 credits (per content piece)
• optimization: 1 credit per 200 words

---

SUCCESS CRITERIA

Phase 3 Success Criteria

• ✅ Site Builder wizard works end-to-end
• ✅ AI structure generation creates valid blueprints
• ✅ Preview renders correctly
• ✅ File management works
• ✅ Shared components work across apps
• ✅ Page generation reuses ContentGenerationService

Phase 4 Success Criteria

• ✅ Linker finds appropriate link candidates
• ✅ Links inject correctly into content
• ✅ Optimizer works from all entry points (Writer, WordPress, 3rd party, Manual)
• ✅ Content source tracking works
• ✅ Pipeline orchestrates correctly
• ✅ UI shows content sources and filters

---

RISK MITIGATION

Phase 3 Risks

1. AI Structure Generation Quality

   • Mitigation: Prompt engineering, validation, user feedback loop

2. Component Compatibility

   • Mitigation: Shared component library, comprehensive testing

3. File Management Security

   • Mitigation: Access control, validation, quota checks

Phase 4 Risks

1. Link Quality

   • Mitigation: Candidate scoring algorithm, relevance checks

2. Optimization Quality

   • Mitigation: Content analysis, before/after comparison, user review

3. Multiple Entry Points Complexity

   • Mitigation: Unified optimization logic, clear entry point methods

---

END OF IMPLEMENTATION PLAN