# 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 ⏳
**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):
```typescript
import axios from 'axios';
const client = axios.create({ baseURL: BASE_PATH });
```

**To** (frontend):
```typescript
import { fetchAPI } from '../services/api';
// Use fetchAPI directly, no axios
```

### 2. Component Library
**From** (sites container):
```typescript
import { Card } from '../../components/common/Card';
```

**To** (frontend):
```typescript
import { Card } from '../../../components/ui/card/Card';
```

### 3. Styling
**From** (sites container):
```css
.sb-field { ... }
.sb-grid { ... }
```

**To** (frontend):
```tsx
className="flex flex-col gap-2"
className="grid grid-cols-2 gap-4"
```

### 4. Store Integration
**From** (sites container):
```typescript
// Manual siteId/sectorId input
```

**To** (frontend):
```typescript
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.