igny8/docs/planning/phases/PHASE-3-SITE-BUILDER.md

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
2. Sites Folder Access & File Management
3. Site Builder Models
4. Site Structure Generation
5. Site Builder API
6. Site Builder Frontend
7. Global Component Library
8. Page Generation
9. Testing & Validation
10. 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:

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

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

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

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

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

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

# 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