# PHASE 3: SITE BUILDER
**Detailed Implementation Plan**

**Goal**: Build Site Builder for creating sites via wizard.

**Timeline**: 3-4 weeks  
**Priority**: HIGH  
**Dependencies**: Phase 1, Phase 2

---

## TABLE OF CONTENTS

1. [Overview](#overview)
2. [Sites Folder Access & File Management](#sites-folder-access--file-management)
3. [Site Builder Models](#site-builder-models)
4. [Site Structure Generation](#site-structure-generation)
5. [Site Builder API](#site-builder-api)
6. [Site Builder Frontend](#site-builder-frontend)
7. [Global Component Library](#global-component-library)
8. [Page Generation](#page-generation)
9. [Testing & Validation](#testing--validation)
10. [Implementation Checklist](#implementation-checklist)

---

## OVERVIEW

### Objectives
- ✅ Create Site Builder wizard for site creation
- ✅ Generate site structure using AI
- ✅ Build preview canvas for site editing
- ✅ Create shared component library
- ✅ Support multiple layouts and templates
- ✅ Enable file management for site assets

### Key Principles
- **Wizard-Based**: Step-by-step site creation process
- **AI-Powered**: AI generates site structure from business brief
- **Component Reuse**: Shared components across Site Builder, Sites Renderer, Main App
- **User-Friendly**: "Website Builder" or "Site Creator" in UI

---

## SITES FOLDER ACCESS & FILE MANAGEMENT

### 3.0 Sites Folder Access & File Management

**Purpose**: Manage site files and assets with proper access control.

#### Sites Folder 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/
```

#### User Access Rules

- **Owner/Admin**: Full access to all account sites
- **Editor**: Access to granted sites (via SiteUserAccess)
- **Viewer**: Read-only access to granted sites
- **File operations**: Scoped to user's accessible sites only

#### Site File Management Service

| Task | File | Dependencies | Implementation |
|------|------|--------------|----------------|
| **Site File Management Service** | `domain/site_building/services/file_management_service.py` | Phase 1 | File upload, delete, organize |

**FileManagementService**:
```python
# domain/site_building/services/file_management_service.py
class SiteBuilderFileService:
    def get_user_accessible_sites(self, user):
        """Get sites user can access for file management"""
        if user.is_owner_or_admin():
            return Site.objects.filter(account=user.account)
        return user.get_accessible_sites()
    
    def get_site_files_path(self, site_id, version=1):
        """Get site's files directory"""
        return f"/data/app/sites-data/clients/{site_id}/v{version}/assets/"
    
    def check_file_access(self, user, site_id):
        """Check if user can access site's files"""
        accessible_sites = self.get_user_accessible_sites(user)
        return any(site.id == site_id for site in accessible_sites)
    
    def upload_file(self, user, site_id, file, folder='images'):
        """Upload file to site's assets folder"""
        if not self.check_file_access(user, site_id):
            raise PermissionDenied("No access to this site")
        
        # Check storage quota
        if not self.check_storage_quota(site_id, file.size):
            raise ValidationError("Storage quota exceeded")
        
        # Upload file
        file_path = self._save_file(site_id, file, folder)
        return file_path
```

#### File Upload API

| Task | File | Dependencies | Implementation |
|------|------|--------------|----------------|
| **File Upload API** | `modules/site_builder/views.py` | File Management Service | Handle file uploads |

#### File Browser UI

| Task | File | Dependencies | Implementation |
|------|------|--------------|----------------|
| **File Browser UI** | `site-builder/src/components/files/FileBrowser.tsx` | NEW | File browser component |

#### Storage Quota Check

| Task | File | Dependencies | Implementation |
|------|------|--------------|----------------|
| **Storage Quota Check** | `infrastructure/storage/file_storage.py` | Phase 1 | Check site storage quota |

---

## SITE BUILDER MODELS

### 3.1 Site Builder Models

**Purpose**: Store site blueprints and page definitions.

#### SiteBlueprint Model

| Task | File | Dependencies | Implementation |
|------|------|--------------|----------------|
| **SiteBlueprint Model** | `domain/site_building/models.py` | Phase 1 | Store site structure |

**SiteBlueprint Model**:
```python
# domain/site_building/models.py
class SiteBlueprint(SiteSectorBaseModel):
    name = models.CharField(max_length=255)
    description = models.TextField(blank=True)
    
    # Site configuration
    config_json = models.JSONField(default=dict)
    # Example: {'business_type': 'ecommerce', 'style': 'modern'}
    
    # Generated structure
    structure_json = models.JSONField(default=dict)
    # Example: {'pages': [...], 'layout': 'default', 'theme': {...}}
    
    # Status tracking
    status = models.CharField(
        max_length=20,
        choices=[
            ('draft', 'Draft'),
            ('generating', 'Generating'),
            ('ready', 'Ready'),
            ('deployed', 'Deployed'),
        ],
        default='draft'
    )
    
    # Hosting configuration
    hosting_type = models.CharField(
        max_length=50,
        choices=[
            ('igny8_sites', 'IGNY8 Sites'),
            ('wordpress', 'WordPress'),
            ('shopify', 'Shopify'),
            ('multi', 'Multiple Destinations'),
        ],
        default='igny8_sites'
    )
    
    # Version tracking
    version = models.IntegerField(default=1)
    deployed_version = models.IntegerField(null=True, blank=True)
    
    class Meta:
        ordering = ['-created_at']
```

#### PageBlueprint Model

| Task | File | Dependencies | Implementation |
|------|------|--------------|----------------|
| **PageBlueprint Model** | `domain/site_building/models.py` | Phase 1 | Store page definitions |

**PageBlueprint Model**:
```python
# domain/site_building/models.py
class PageBlueprint(SiteSectorBaseModel):
    site_blueprint = models.ForeignKey(SiteBlueprint, on_delete=models.CASCADE, related_name='pages')
    slug = models.SlugField(max_length=255)
    title = models.CharField(max_length=255)
    
    # Page type
    type = models.CharField(
        max_length=50,
        choices=[
            ('home', 'Home'),
            ('about', 'About'),
            ('services', 'Services'),
            ('products', 'Products'),
            ('blog', 'Blog'),
            ('contact', 'Contact'),
            ('custom', 'Custom'),
        ]
    )
    
    # Page content (blocks)
    blocks_json = models.JSONField(default=list)
    # Example: [{'type': 'hero', 'data': {...}}, {'type': 'features', 'data': {...}}]
    
    # Status
    status = models.CharField(
        max_length=20,
        choices=[
            ('draft', 'Draft'),
            ('generating', 'Generating'),
            ('ready', 'Ready'),
        ],
        default='draft'
    )
    
    # Order
    order = models.IntegerField(default=0)
    
    class Meta:
        ordering = ['order', 'created_at']
        unique_together = [['site_blueprint', 'slug']]
```

#### Site Builder Migrations

| Task | File | Dependencies | Implementation |
|------|------|--------------|----------------|
| **Site Builder Migrations** | `domain/site_building/migrations/` | Phase 1 | Create initial migrations |

---

## SITE STRUCTURE GENERATION

### 3.2 Site Structure Generation

**Purpose**: Use AI to generate site structure from business brief.

#### Structure Generation AI Function

| Task | File | Dependencies | Implementation |
|------|------|--------------|----------------|
| **Structure Generation AI Function** | `infrastructure/ai/functions/generate_site_structure.py` | Existing AI framework | AI function for structure generation |

**GenerateSiteStructureFunction**:
```python
# infrastructure/ai/functions/generate_site_structure.py
class GenerateSiteStructureFunction(BaseAIFunction):
    def get_operation_type(self):
        return 'site_structure_generation'
    
    def get_estimated_cost(self, payload):
        return CREDIT_COSTS['site_structure_generation']
    
    def execute(self, payload, account):
        """Generate site structure from business brief"""
        business_brief = payload['business_brief']
        objectives = payload.get('objectives', [])
        style_preferences = payload.get('style', {})
        
        # Build prompt
        prompt = self._build_prompt(business_brief, objectives, style_preferences)
        
        # Call AI
        response = self.ai_core.generate(prompt, model='gpt-4')
        
        # Parse response to structure JSON
        structure = self._parse_structure(response)
        
        return structure
```

#### Structure Generation Service

| Task | File | Dependencies | Implementation |
|------|------|--------------|----------------|
| **Structure Generation Service** | `domain/site_building/services/structure_generation_service.py` | Phase 1, AI framework | Service to generate site structure |

**StructureGenerationService**:
```python
# domain/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):
        """Generate site structure for blueprint"""
        account = site_blueprint.account
        
        # Check credits
        self.credit_service.check_credits(account, 'site_structure_generation')
        
        # Update status
        site_blueprint.status = 'generating'
        site_blueprint.save()
        
        # Generate structure
        payload = {
            'business_brief': business_brief,
            'objectives': objectives,
            'style': style,
        }
        structure = self.ai_function.execute(payload, account)
        
        # Deduct credits
        self.credit_service.deduct_credits(account, 'site_structure_generation')
        
        # Update blueprint
        site_blueprint.structure_json = structure
        site_blueprint.status = 'ready'
        site_blueprint.save()
        
        # Create page blueprints
        self._create_page_blueprints(site_blueprint, structure)
        
        return site_blueprint
```

#### Site Structure Prompts

| Task | File | Dependencies | Implementation |
|------|------|--------------|----------------|
| **Site Structure Prompts** | `infrastructure/ai/prompts.py` | Existing prompt system | Add site structure prompts |

---

## SITE BUILDER API

### 3.3 Site Builder API

**Purpose**: API endpoints for site builder operations.

#### Site Builder ViewSet

| Task | File | Dependencies | Implementation |
|------|------|--------------|----------------|
| **Site Builder ViewSet** | `modules/site_builder/views.py` | Structure Generation Service | CRUD operations for site blueprints |

**SiteBuilderViewSet**:
```python
# modules/site_builder/views.py
class SiteBuilderViewSet(AccountModelViewSet):
    queryset = SiteBlueprint.objects.all()
    serializer_class = SiteBlueprintSerializer
    
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.structure_service = StructureGenerationService()
    
    @action(detail=True, methods=['post'])
    def generate_structure(self, request, pk=None):
        """Generate site structure"""
        blueprint = self.get_object()
        business_brief = request.data.get('business_brief')
        objectives = request.data.get('objectives', [])
        style = request.data.get('style', {})
        
        blueprint = self.structure_service.generate_structure(
            blueprint, business_brief, objectives, style
        )
        
        serializer = self.get_serializer(blueprint)
        return Response(serializer.data)
```

#### Site Builder URLs

| Task | File | Dependencies | Implementation |
|------|------|--------------|----------------|
| **Site Builder URLs** | `modules/site_builder/urls.py` | None | Register site builder routes |

#### Site Builder Serializers

| Task | File | Dependencies | Implementation |
|------|------|--------------|----------------|
| **Site Builder Serializers** | `modules/site_builder/serializers.py` | None | Serializers for SiteBlueprint and PageBlueprint |

---

## SITE BUILDER FRONTEND

### 3.4 Site Builder Frontend (New Container)

**User-Friendly Name**: "Website Builder" or "Site Creator"

#### Create Site Builder Container

| Task | File | Dependencies | Implementation |
|------|------|--------------|----------------|
| **Create Site Builder Container** | `docker-compose.app.yml` | None | Add new container for site builder |

**Docker Compose Configuration**:
```yaml
# docker-compose.app.yml
igny8_site_builder:
  build: ./site-builder
  ports:
    - "8022:5175"
  volumes:
    - /data/app/igny8/site-builder:/app
  environment:
    - VITE_API_URL=http://igny8_backend:8010
```

#### Wizard Steps

| Task | File | Dependencies | Implementation |
|------|------|--------------|----------------|
| **Wizard Steps** | `site-builder/src/pages/wizard/` | NEW | Step-by-step wizard components |

**Wizard Steps**:
- Step 1: Type Selection (Business type, industry)
- Step 2: Business Brief (Description, goals)
- Step 3: Objectives (What pages needed)
- Step 4: Style Preferences (Colors, fonts, layout)

#### Preview Canvas

| Task | File | Dependencies | Implementation |
|------|------|--------------|----------------|
| **Preview Canvas** | `site-builder/src/pages/preview/` | NEW | Live preview of site |

#### Site Builder State

| Task | File | Dependencies | Implementation |
|------|------|--------------|----------------|
| **Site Builder State** | `site-builder/src/state/builderStore.ts` | NEW | Zustand store for builder state |

#### Site Builder API Client

| Task | File | Dependencies | Implementation |
|------|------|--------------|----------------|
| **Site Builder API Client** | `site-builder/src/api/builder.api.ts` | NEW | API client for site builder |

#### Layout Selection

| Task | File | Dependencies | Implementation |
|------|------|--------------|----------------|
| **Layout Selection** | `site-builder/src/components/layouts/` | NEW | Layout selector component |

#### Template Library

| Task | File | Dependencies | Implementation |
|------|------|--------------|----------------|
| **Template Library** | `site-builder/src/components/templates/` | NEW | Template selector component |

#### Block Components

| Task | File | Dependencies | Implementation |
|------|------|--------------|----------------|
| **Block Components** | `site-builder/src/components/blocks/` | NEW | Block components (imports from shared) |

---

## GLOBAL COMPONENT LIBRARY

### 3.7 Global Component Library

**Purpose**: Shared components across Site Builder, Sites Renderer, and Main App.

#### Create Shared Component Library

| Task | File | Dependencies | Implementation |
|------|------|--------------|----------------|
| **Create Shared Component Library** | `frontend/src/components/shared/` | None | Create shared component structure |

**Component Library Structure**:
```
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
    └── ...
```

**Usage**: Site Builder, Sites Renderer, and Main App all use same components (no duplicates)

#### Component Documentation

| Task | File | Dependencies | Implementation |
|------|------|--------------|----------------|
| **Component Documentation** | `frontend/src/components/shared/README.md` | None | Document all shared components |

---

## PAGE GENERATION

### 3.5 Page Generation (Reuse Content Service)

**Purpose**: Generate page content using existing ContentService.

#### Extend ContentService

| Task | File | Dependencies | Implementation |
|------|------|--------------|----------------|
| **Extend ContentService** | `domain/content/services/content_generation_service.py` | Phase 1 | Add site page generation method |

#### Add Site Page Type

| Task | File | Dependencies | Implementation |
|------|------|--------------|----------------|
| **Add Site Page Type** | `domain/content/models.py` | Phase 1 | Add site page content type |

#### Page Generation Prompts

| Task | File | Dependencies | Implementation |
|------|------|--------------|----------------|
| **Page Generation Prompts** | `infrastructure/ai/prompts.py` | Existing prompt system | Add page generation prompts |

---

## TESTING & VALIDATION

### 3.6 Testing

**Test Cases**:

1. **Site Builder Tests**:
   - ✅ Site Builder wizard works end-to-end
   - ✅ Structure generation creates valid blueprints
   - ✅ Preview renders correctly
   - ✅ Page generation reuses existing content service

2. **File Management Tests**:
   - ✅ File upload works
   - ✅ File access control works
   - ✅ Storage quota enforced

3. **Component Library Tests**:
   - ✅ Components render correctly
   - ✅ Components work in Site Builder
   - ✅ Components work in Sites Renderer

---

## IMPLEMENTATION CHECKLIST

### Backend Tasks

- [ ] Create `domain/site_building/models.py`
- [ ] Create SiteBlueprint model
- [ ] Create PageBlueprint model
- [ ] Create site builder migrations
- [ ] Create `domain/site_building/services/file_management_service.py`
- [ ] Create `domain/site_building/services/structure_generation_service.py`
- [ ] Create `infrastructure/ai/functions/generate_site_structure.py`
- [ ] Add site structure prompts
- [ ] Create `modules/site_builder/views.py`
- [ ] Create SiteBuilder ViewSet
- [ ] Create `modules/site_builder/serializers.py`
- [ ] Create `modules/site_builder/urls.py`
- [ ] Extend ContentService for page generation

### Frontend Tasks

- [ ] Create `site-builder/` folder structure
- [ ] Create Site Builder container in docker-compose
- [ ] Create wizard steps
- [ ] Create preview canvas
- [ ] Create builder state store
- [ ] Create API client
- [ ] Create layout selector
- [ ] Create template library
- [ ] Create `frontend/src/components/shared/` structure
- [ ] Create block components
- [ ] Create layout components
- [ ] Create template components
- [ ] Create component documentation

### Testing Tasks

- [ ] Test site builder wizard
- [ ] Test structure generation
- [ ] Test file management
- [ ] Test component library
- [ ] Test page generation

---

## RISK ASSESSMENT

| Risk | Level | Mitigation |
|------|-------|------------|
| **AI structure generation quality** | MEDIUM | Prompt engineering, validation |
| **Component compatibility** | MEDIUM | Shared component library, testing |
| **File management security** | MEDIUM | Access control, validation |
| **Performance with large sites** | LOW | Optimization, caching |

---

## SUCCESS CRITERIA

- ✅ Site Builder wizard works end-to-end
- ✅ Structure generation creates valid blueprints
- ✅ Preview renders correctly
- ✅ Page generation reuses existing content service
- ✅ File management works correctly
- ✅ Shared components work across all apps
- ✅ Multiple layouts supported

---

**END OF PHASE 3 DOCUMENT**