igny8/SITE_BUILDER_INTEGRATION_PLAN.md

Site Builder Wizard Integration Plan

Overview

Integrate the Site Builder wizard directly into the main frontend app (frontend/src/pages/Sites/Builder/), using the same UI kit, state stores, and API helpers as the rest of the dashboard. The legacy sites/src/builder + sites/src/renderer code has been removed, so the only viable implementation path is the unified Sites module.

Current State

✅ What's Done

• Legacy builder/renderer folders removed from Sites container (no more parallel UI)
• Type definitions created in frontend/src/types/siteBuilder.ts
• API helper created in frontend/src/services/siteBuilder.api.ts

⚠️ What's Missing

• Builder store not yet created in the main app
• Wizard steps/page still placeholder in frontend/src/pages/Sites/Builder/
• No Tailwind/CX styling hooked into shared UI kit
• Routes/menu point to placeholder
• Tests/docs still reference old structure
• Sites container still contains stale references (needs cleanup after integration)

Integration Plan

Phase 1: Create API Service Layer ✅

Location: frontend/src/services/siteBuilder.api.ts

Tasks:

1. Create siteBuilderApi using fetchAPI pattern (not axios)
2. Functions needed:
   • listBlueprints()
   • createBlueprint(payload)
   • generateStructure(blueprintId, payload)
   • listPages(blueprintId)
   • generateAllPages(blueprintId, options)
   • createTasksForPages(blueprintId, pageIds)

API Endpoints (already exist in backend):

• GET /api/v1/site-builder/blueprints/
• POST /api/v1/site-builder/blueprints/
• POST /api/v1/site-builder/blueprints/{id}/generate_structure/
• GET /api/v1/site-builder/pages/?site_blueprint={id}
• POST /api/v1/site-builder/blueprints/{id}/generate_all_pages/
• POST /api/v1/site-builder/blueprints/{id}/create_tasks/

Phase 2: Create Zustand Store ⏳

Location: frontend/src/store/builderStore.ts

Tasks:

1. Copy builderStore.ts from sites/src/builder/state/
2. Adapt to use siteBuilderApi instead of builderApi
3. Integrate with useSiteStore and useSectorStore:
   • Auto-populate siteId from useSiteStore().activeSite
   • Auto-populate sectorId from useSectorStore().activeSector
   • Show site/sector selector if not set

Store State:

• form: BuilderFormData - Wizard form data
• currentStep: number - Current wizard step (0-3)
• isSubmitting: boolean - Generation in progress
• activeBlueprint: SiteBlueprint | null - Latest blueprint
• pages: PageBlueprint[] - Generated pages
• error: string | null - Error message

Phase 3: Create Type Definitions ✅

Location: frontend/src/types/siteBuilder.ts

Tasks:

1. Copy types from sites/src/builder/types/siteBuilder.ts
2. Ensure compatibility with frontend's existing types

Types Needed:

• HostingType
• StylePreferences
• BuilderFormData
• SiteBlueprint
• PageBlueprint
• PageBlock
• SiteStructure

Phase 4: Create Wizard Step Components ⏳

Location: frontend/src/pages/Sites/Builder/steps/

Tasks:

1. Copy step components from sites/src/builder/pages/wizard/steps/
2. Adapt to use frontend's UI components:
   • Replace Card with frontend/src/components/ui/card/Card
   • Replace custom inputs with Tailwind-styled inputs
   • Use frontend's Button component
3. Adapt styles to Tailwind CSS:
   • Remove .sb-field, .sb-grid, .sb-pill classes
   • Use Tailwind utility classes instead

Step Components:

• BusinessDetailsStep.tsx - Site/sector selection, business info
• BriefStep.tsx - Business brief textarea
• ObjectivesStep.tsx - Objectives list with add/remove
• StyleStep.tsx - Style preferences (palette, typography, personality)

Phase 5: Create Main Wizard Page ⏳

Location: frontend/src/pages/Sites/Builder/Wizard.tsx

Tasks:

1. Copy WizardPage.tsx from sites/src/builder/pages/wizard/
2. Adapt to frontend patterns:
   • Use PageMeta component
   • Use frontend's Card component
   • Use frontend's Button component
   • Use Tailwind CSS for styling
3. Integrate with stores:
   • Auto-load active site/sector
   • Show site/sector selector if needed
   • Navigate to sites list on completion

Features:

• 4-step wizard with progress indicators
• Step navigation (Back/Next buttons)
• Form validation
• Blueprint generation on submit
• Error handling
• Loading states

Phase 6: Create Site Definition Store (Optional) ⏳

Location: frontend/src/store/siteDefinitionStore.ts

Tasks:

1. Copy siteDefinitionStore.ts from sites/src/builder/state/
2. Use for preview functionality (if needed)

Phase 7: Update Routing & Navigation ✅

Location: frontend/src/App.tsx

Tasks:

1. Ensure /sites/builder route points to new Wizard.tsx
2. Update navigation to show wizard in Sites section

Phase 8: Fix Test File ✅

Location: frontend/src/__tests__/sites/BulkGeneration.test.tsx

Tasks:

1. Update import path from site-builder/src/api/builder.api to services/siteBuilder.api
2. Update mock path accordingly

Phase 9: Testing ⏳ (blocked by vitest not installed in dev env)

Tasks:

1. Test wizard flow:
   • Site selection
   • Sector selection
   • All 4 wizard steps
   • Blueprint generation
   • Error handling
2. Test integration:
   • Site/sector auto-population
   • Navigation
   • API calls

Phase 10: Cleanup ⏳

Tasks:

1. Stop igny8_site_builder container
2. Remove Docker image
3. Remove /site-builder folder
4. Update documentation

File Structure After Integration

frontend/src/
├── pages/Sites/Builder/
│   ├── Wizard.tsx              # Main wizard page (UPDATED)
│   ├── Preview.tsx             # Preview page (keep placeholder for now)
│   ├── Blueprints.tsx          # Blueprints list (already exists)
│   └── steps/                  # NEW
│       ├── BusinessDetailsStep.tsx
│       ├── BriefStep.tsx
│       ├── ObjectivesStep.tsx
│       └── StyleStep.tsx
├── services/
│   └── siteBuilder.api.ts      # NEW - API service
├── store/
│   ├── builderStore.ts         # NEW - Builder state
│   └── siteDefinitionStore.ts  # NEW - Site definition state (optional)
└── types/
    └── siteBuilder.ts          # NEW - Type definitions

Key Adaptations Needed

1. API Client Pattern

From (sites container):

import axios from 'axios';
const client = axios.create({ baseURL: BASE_PATH });

To (frontend):

import { fetchAPI } from '../services/api';
// Use fetchAPI directly, no axios

2. Component Library

From (sites container):

import { Card } from '../../components/common/Card';

To (frontend):

import { Card } from '../../../components/ui/card/Card';

3. Styling

From (sites container):

.sb-field { ... }
.sb-grid { ... }

To (frontend):

className="flex flex-col gap-2"
className="grid grid-cols-2 gap-4"

4. Store Integration

From (sites container):

// Manual siteId/sectorId input

To (frontend):

import { useSiteStore } from '../../../store/siteStore';
import { useSectorStore } from '../../../store/sectorStore';
// Auto-populate from stores

Implementation Order

1. ✅ Create types (types/siteBuilder.ts)
2. ✅ Create API service (services/siteBuilder.api.ts)
3. ⏳ Create builder store (store/builderStore.ts)
4. ⏳ Create step components (pages/Sites/Builder/steps/)
5. ⏳ Create main wizard page (pages/Sites/Builder/Wizard.tsx)
6. ⏳ Fix test file(s)
7. ⏳ Test integration
8. ⏳ Cleanup site-builder container/image/docs

Success Criteria

• ✅ Wizard loads in main app at /sites/builder
• ✅ Site/sector auto-populated from stores
• ✅ All 4 steps work correctly
• ✅ Blueprint generation works
• ✅ Error handling works
• ✅ Navigation works
• ✅ No references to site-builder/ folder in code
• ✅ Test file updated
• ✅ Sites container removed or marked deprecated in compose

Notes

• Sites container will be deprecated once the wizard lives entirely inside the main app.
• Only integrate wizard into main frontend app (no parallel codepaths).
• Use frontend's existing patterns/components/stores for absolute consistency.