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  
**Last Updated**: 2025-01-XX  
**Status**: Phase 3 Complete ✅ | Phase 4 Complete ✅

---

## TABLE OF CONTENTS

1. [Implementation Summary](#implementation-summary) ⭐ **NEW**
2. [Overview](#overview)
3. [Phase 3: Site Builder Implementation Plan](#phase-3-site-builder-implementation-plan)
4. [Phase 4: Linker & Optimizer Implementation Plan](#phase-4-linker--optimizer-implementation-plan)
5. [Integration Points](#integration-points)
6. [File Structure](#file-structure)
7. [Dependencies & Order](#dependencies--order)
8. [Testing Strategy](#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 - 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

#### Frontend Implementation

**API Clients** (`frontend/src/api/`):
- ✅ `linker.api.ts` - Linker API functions (`process`, `batchProcess`)
- ✅ `optimizer.api.ts` - Optimizer API functions (`optimize`, `batchOptimize`, `analyze`)

**Shared Components** (`frontend/src/components/content/`):
- ✅ `SourceBadge.tsx` - Displays content source (igny8, wordpress, shopify, custom)
- ✅ `SyncStatusBadge.tsx` - Displays sync status (native, imported, synced)
- ✅ `ContentFilter.tsx` - Filters content by source and sync status
- ✅ `index.ts` - Barrel exports

**Linker Components** (`frontend/src/components/linker/`):
- ✅ `LinkResults.tsx` - Displays linking results with links added count

**Optimizer Components** (`frontend/src/components/optimizer/`):
- ✅ `OptimizationScores.tsx` - Displays optimization scores (SEO, readability, engagement, overall)
- ✅ `ScoreComparison.tsx` - Compares before/after optimization scores

**Linker Pages** (`frontend/src/pages/Linker/`):
- ✅ `Dashboard.tsx` - Linker dashboard with stats and quick actions
- ✅ `ContentList.tsx` - Content list with link processing actions

**Optimizer Pages** (`frontend/src/pages/Optimizer/`):
- ✅ `Dashboard.tsx` - Optimizer dashboard with stats and quick actions
- ✅ `ContentSelector.tsx` - Content selector with batch optimization and filters
- ✅ `AnalysisPreview.tsx` - Analysis preview page for content scores

**Routing & Navigation**:
- ✅ Added Linker routes to `App.tsx` (`/linker`, `/linker/content`)
- ✅ Added Optimizer routes to `App.tsx` (`/optimizer`, `/optimizer/content`, `/optimizer/analyze/:id`)
- ✅ Updated `routes.config.ts` with Linker and Optimizer menu items
- ✅ Added Linker and Optimizer to sidebar navigation menu (`AppSidebar.tsx`)

**Writer Integration**:
- ✅ Added source and sync status columns to Writer Content table
- ✅ Added source and sync status filters to Writer Content list
- ✅ Added "Optimize" action to Writer content rows
- ✅ Added "Send to Optimizer" action in Writer
- ✅ Updated `content.config.tsx` with source and sync status columns and filters

**AI Function Created**:
- ✅ `OptimizeContentFunction` (`ai/functions/optimize_content.py`)
  - Operation type: `optimize_content`
  - Credit cost: 1 credit per 200 words (from constants)
  - Optimizes content for SEO, readability, engagement
  - All phases implemented: INIT, PREP, AI_CALL, PARSE, SAVE, DONE
- ✅ Added to AI registry (`ai/registry.py`)
- ✅ Added prompt to `ai/prompts.py` (`optimize_content`)
- ✅ Integrated into `OptimizerService._optimize_content()`

**API Layer Created** (`modules/linker/` and `modules/optimizer/`):
- ✅ `LinkerViewSet` with actions:
  - `process/` (POST) - Process content for linking
  - `batch_process/` (POST) - Process multiple content items
- ✅ `OptimizerViewSet` with actions:
  - `optimize/` (POST) - Optimize content (auto-detects entry point)
  - `batch_optimize/` (POST) - Batch optimize multiple content items
  - `analyze/` (POST) - Analyze content without optimizing
- ✅ Serializers:
  - `LinkContentSerializer`, `BatchLinkContentSerializer`
  - `OptimizeContentSerializer`, `BatchOptimizeContentSerializer`, `AnalyzeContentSerializer`
- ✅ URLs registered at `/api/v1/linker/` and `/api/v1/optimizer/`
- ✅ Added to `INSTALLED_APPS` in `settings.py`
- ✅ Throttle rates configured: `linker: 30/min`, `optimizer: 10/min`

**Note**: Phase 4 frontend UI is **now complete** ✅

### 📋 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/igny8_core/business/linking/tests/__init__.py`
- `backend/igny8_core/business/linking/tests/test_linker_service.py`
- `backend/igny8_core/business/linking/tests/test_candidate_engine.py`
- `backend/igny8_core/business/linking/tests/test_injection_engine.py`
- `backend/igny8_core/business/optimization/tests/__init__.py`
- `backend/igny8_core/business/optimization/tests/test_optimizer_service.py`
- `backend/igny8_core/business/optimization/tests/test_analyzer.py`
- `backend/igny8_core/business/content/tests/__init__.py`
- `backend/igny8_core/business/content/tests/test_content_pipeline_service.py`
- `backend/igny8_core/business/billing/tests/__init__.py`
- `backend/igny8_core/business/billing/tests/test_phase4_credits.py`
- `backend/igny8_core/modules/linker/tests/__init__.py`
- `backend/igny8_core/modules/linker/tests/test_views.py`
- `backend/igny8_core/modules/optimizer/tests/__init__.py`
- `backend/igny8_core/modules/optimizer/tests/test_views.py`
- `backend/igny8_core/ai/functions/tests/__init__.py`
- `backend/igny8_core/ai/functions/tests/test_optimize_content.py`

#### Backend Files Modified

- `backend/igny8_core/settings.py` - Added Site Builder, Linker, Optimizer apps to `INSTALLED_APPS`; Added throttle rates
- `backend/igny8_core/urls.py` - Added Site Builder, Linker, Optimizer URL routing
- `backend/igny8_core/ai/registry.py` - Registered `GenerateSiteStructureFunction` and `OptimizeContentFunction`
- `backend/igny8_core/ai/prompts.py` - Added `site_structure_generation` and `optimize_content` prompts
- `backend/igny8_core/ai/engine.py` - Integrated site structure generation
- `backend/igny8_core/business/content/models.py` - Added Phase 4 fields
- `backend/igny8_core/business/optimization/services/optimizer_service.py` - Updated `_optimize_content()` to use AI function
- `backend/igny8_core/modules/writer/serializers.py` - Fixed `Content.DoesNotExist` handling
- `frontend/src/App.tsx` - Added Linker and Optimizer routes
- `frontend/src/config/routes.config.ts` - Added Linker and Optimizer menu items
- `frontend/src/layout/AppSidebar.tsx` - Added Linker and Optimizer to sidebar navigation
- `frontend/src/config/pages/content.config.tsx` - Added source and sync status columns and filters
- `frontend/src/pages/Writer/Content.tsx` - Added optimize action, source/sync filters

#### 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`
- `frontend/src/components/content/__tests__/SourceBadge.test.tsx`
- `frontend/src/components/content/__tests__/SyncStatusBadge.test.tsx`
- `frontend/src/components/content/__tests__/ContentFilter.test.tsx`
- `frontend/src/pages/Linker/__tests__/Dashboard.test.tsx`
- `frontend/src/pages/Linker/__tests__/ContentList.test.tsx`
- `frontend/src/pages/Optimizer/__tests__/Dashboard.test.tsx`
- `frontend/src/pages/Optimizer/__tests__/ContentSelector.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`

**Phase 4 Frontend Components**:
- `frontend/src/api/linker.api.ts`
- `frontend/src/api/optimizer.api.ts`
- `frontend/src/components/content/SourceBadge.tsx`
- `frontend/src/components/content/SyncStatusBadge.tsx`
- `frontend/src/components/content/ContentFilter.tsx`
- `frontend/src/components/content/index.ts`
- `frontend/src/components/linker/LinkResults.tsx`
- `frontend/src/components/optimizer/OptimizationScores.tsx`
- `frontend/src/components/optimizer/ScoreComparison.tsx`
- `frontend/src/pages/Linker/Dashboard.tsx`
- `frontend/src/pages/Linker/ContentList.tsx`
- `frontend/src/pages/Optimizer/Dashboard.tsx`
- `frontend/src/pages/Optimizer/ContentSelector.tsx`
- `frontend/src/pages/Optimizer/AnalysisPreview.tsx`

#### 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 - COMPLETE ✅

**All Phase 4 implementation tasks completed in this session:**

**Backend**:
- ✅ AI Function (`OptimizeContentFunction`) created and integrated
- ✅ Linker API module (`modules/linker/`) with ViewSet, serializers, URLs
- ✅ Optimizer API module (`modules/optimizer/`) with ViewSet, serializers, URLs
- ✅ Settings and URL routing configured
- ✅ 10 backend test files created (70+ test cases)

**Frontend**:
- ✅ API clients (`linker.api.ts`, `optimizer.api.ts`)
- ✅ Shared components (SourceBadge, SyncStatusBadge, ContentFilter, LinkResults, OptimizationScores, ScoreComparison)
- ✅ Linker pages (Dashboard, ContentList)
- ✅ Optimizer pages (Dashboard, ContentSelector, AnalysisPreview)
- ✅ Writer integration (source badges, filters, optimize actions)
- ✅ Routing and navigation (routes, sidebar menu)
- ✅ 7 frontend test files created (30+ test cases)

**Summary**: Phase 4 is 100% complete with all backend services, AI functions, API endpoints, frontend UI, and comprehensive test coverage.

### 📊 Implementation Statistics

- **Backend Files Created**: 40+
- **Frontend Files Created**: 45+
- **Backend Tests**: 13 test files, 70+ test cases
- **Frontend Tests**: 11 test files, 30+ test cases
- **Lines of Code**: ~8,000+ (backend + frontend)
- **Docker Containers**: 1 new container (`igny8_site_builder`)
- **API Endpoints**: 15+ new endpoints
- **Database Tables**: 2 new tables (`SiteBlueprint`, `PageBlueprint`)
- **Migrations**: 2 migrations created and applied

#### Phase 4 Statistics (This Session)
- **Backend Files Created**: 15+
  - AI Function: 1 file
  - API Modules: 6 files (linker + optimizer)
  - Test Files: 10 files
- **Frontend Files Created**: 20+
  - API Clients: 2 files
  - Components: 6 files
  - Pages: 5 files
  - Test Files: 7 files
- **Backend Test Cases**: 70+ individual test methods
- **Frontend Test Cases**: 30+ individual test methods

---

## 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`)
   ```python
   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`)
   ```python
   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`)
   ```python
   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**
   - [x] Create `business/site_building/` folder
   - [x] Create `SiteBlueprint` model
   - [x] Create `PageBlueprint` model
   - [x] Create migrations

2. **Create Services**
   - [x] Create `FileManagementService`
   - [x] Create `StructureGenerationService`
   - [x] Create `PageGenerationService`
   - [x] Integrate with `CreditService`

3. **Create AI Function**
   - [x] Create `GenerateSiteStructureFunction`
   - [x] Add prompts for site structure generation
   - [x] Test AI function

4. **Create API Layer**
   - [x] Create `modules/site_builder/` folder
   - [x] Create `SiteBuilderViewSet`
   - [x] Create `PageBlueprintViewSet`
   - [x] Create `FileUploadView`
   - [x] Create serializers
   - [x] Register URLs

#### Frontend Tasks (Priority Order)

1. **Create Site Builder Container**
   - [x] Create `site-builder/` folder structure
   - [x] Set up Vite + React + TypeScript
   - [x] Configure Docker container
   - [x] Set up routing

2. **Create Wizard**
   - [x] Step 1: Business Details (Type Selection)
   - [x] Step 2: Business Brief
   - [x] Step 3: Objectives
   - [x] Step 4: Style Preferences
   - [x] Wizard state management

3. **Create Preview Canvas**
   - [x] Preview renderer
   - [x] Block rendering
   - [x] Layout rendering

4. **Create Shared Components**
   - [x] Block components
   - [x] Layout components
   - [x] 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`**:

```python
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`)
   ```python
   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`)
   ```python
   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`)
   ```python
   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`)
   ```python
   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`)
   ```python
   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`)
   ```python
   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**
   - [x] Add `source` field
   - [x] Add `sync_status` field
   - [x] Add `external_id`, `external_url`, `sync_metadata`
   - [x] Add `internal_links`, `linker_version`
   - [x] Add `optimizer_version`, `optimization_scores`
   - [x] Create migration

2. **Create Linking Services**
   - [x] Create `business/linking/` folder
   - [x] Create `LinkerService`
   - [x] Create `CandidateEngine`
   - [x] Create `InjectionEngine`
   - [x] Integrate with `CreditService`

3. **Create Optimization Services**
   - [x] Create `business/optimization/` folder
   - [x] Create `OptimizationTask` model
   - [x] Create `OptimizerService` (with multiple entry points)
   - [x] Create `ContentAnalyzer`
   - [x] Integrate with `CreditService`

4. **Create AI Function**
   - [x] Create `OptimizeContentFunction`
   - [x] Add optimization prompts
   - [x] Test AI function

5. **Create Pipeline Service**
   - [x] Create `ContentPipelineService`
   - [x] Integrate Linker and Optimizer

6. **Create API Layer**
   - [x] Create `modules/linker/` folder
   - [x] Create `LinkerViewSet`
   - [x] Create `modules/optimizer/` folder
   - [x] Create `OptimizerViewSet`
   - [x] Create serializers
   - [x] Register URLs

#### Frontend Tasks (Priority Order)

1. **Create Linker UI**
   - [x] Linker Dashboard
   - [x] Content List
   - [x] Link Results display

2. **Create Optimizer UI**
   - [x] Optimizer Dashboard
   - [x] Content Selector (with source filters)
   - [x] Optimization Results
   - [x] Score Comparison
   - [x] Analysis Preview

3. **Create Shared Components**
   - [x] SourceBadge component
   - [x] SyncStatusBadge component
   - [x] ContentFilter component
   - [x] LinkResults component
   - [x] OptimizationScores component
   - [x] ScoreComparison component

4. **Update Content List**
   - [x] Add source badges
   - [x] Add sync status badges
   - [x] Add filters (by source, sync_status)
   - [x] Add "Optimize" action button
   - [x] Add "Send to Optimizer" action

---

## 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 ✅ COMPLETE

1. **Backend Tests** ✅
   - ✅ Test Content model extensions (via service tests)
   - ✅ Test LinkerService (`test_linker_service.py` - 8 test cases)
   - ✅ Test CandidateEngine (`test_candidate_engine.py` - 6 test cases)
   - ✅ Test InjectionEngine (`test_injection_engine.py` - 6 test cases)
   - ✅ Test OptimizerService (`test_optimizer_service.py` - 10 test cases)
   - ✅ Test ContentAnalyzer (`test_analyzer.py` - 8 test cases)
   - ✅ Test ContentPipelineService (`test_content_pipeline_service.py` - 10 test cases)
   - ✅ Test credit deduction (`test_phase4_credits.py` - 8 test cases)
   - ✅ Test Linker API endpoints (`test_views.py` - 9 test cases)
   - ✅ Test Optimizer API endpoints (`test_views.py` - 10 test cases)
   - ✅ Test OptimizeContentFunction (`test_optimize_content.py` - 10 test cases)
   - **Total**: 10 test files, 85+ test cases

2. **Frontend Tests** ✅
   - ✅ Test SourceBadge component (`SourceBadge.test.tsx`)
   - ✅ Test SyncStatusBadge component (`SyncStatusBadge.test.tsx`)
   - ✅ Test ContentFilter component (`ContentFilter.test.tsx`)
   - ✅ Test Linker Dashboard (`Dashboard.test.tsx`)
   - ✅ Test Linker ContentList (`ContentList.test.tsx`)
   - ✅ Test Optimizer Dashboard (`Dashboard.test.tsx`)
   - ✅ Test Optimizer ContentSelector (`ContentSelector.test.tsx`)
   - **Total**: 7 test files, 30+ test cases

### 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
- ✅ API endpoints functional and tested
- ✅ AI function integrated and working
- ✅ Credit deduction working at all stages
- ✅ Frontend UI complete with all dashboards and selectors
- ✅ Writer integration complete with badges and filters
- ✅ Navigation and routing complete
- ✅ Backend tests complete (10 test files)
- ✅ Frontend tests complete (7 test files)

---

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