igny8/docs/SITEBUILDER-REMOVAL-MIGRATION-GUIDE.md

SiteBuilder Removal - Complete Migration Guide

Date: December 1, 2025
Status: Code changes completed, database migration pending

---

Summary

All SiteBuilder and Blueprint functionality has been removed from the IGNY8 system. The taxonomy system has been simplified to use the direct Content.taxonomy_terms many-to-many relationship with the ContentTaxonomy model.

---

What Was Removed

Backend Models (Django)

• ✅ SiteBlueprint - Site structure blueprints
• ✅ PageBlueprint - Individual page definitions
• ✅ SiteBlueprintCluster - Cluster to blueprint mappings
• ✅ SiteBlueprintTaxonomy - Blueprint taxonomy definitions
• ✅ BusinessType, AudienceProfile, BrandPersonality, HeroImageryDirection - SiteBuilder metadata options
• ✅ ContentTaxonomyMap - Replaced by Content.taxonomy_terms M2M field

Backend Modules

• ✅ Removed entire igny8_core.modules.site_builder module
• ✅ Removed from INSTALLED_APPS in settings.py
• ✅ Removed /api/v1/site-builder/ URL patterns
• ✅ Cleaned up site_building/models.py, site_building/admin.py

Backend Services & Views

• ✅ Updated PublisherService - removed publish_to_sites() method
• ✅ Updated PublisherViewSet - removed blueprint publishing actions
• ✅ Updated DeploymentRecordViewSet - removed blueprint references
• ✅ Updated PublishingRecord model - removed site_blueprint field
• ✅ Updated DeploymentRecord model - removed site_blueprint field
• ✅ Fixed metadata_mapping_service.py - removed ContentTaxonomyMap
• ✅ Fixed candidate_engine.py - uses Content.taxonomy_terms now
• ✅ Fixed sites_renderer_adapter.py - uses M2M taxonomy relationship
• ✅ Fixed planner/serializers.py - removed SiteBlueprintTaxonomy import

Frontend

• ✅ Removed frontend/src/modules/siteBuilder/ directory
• ✅ Removed frontend/src/types/siteBuilder.ts
• ✅ Removed frontend/src/services/siteBuilder.api.ts
• ✅ Removed SiteBlueprint API functions from services/api.ts
• ✅ Removed SiteBuilder routes from navigation

---

Current Taxonomy System

Simplified Architecture

Before (Complex - SiteBuilder era):

Content → ContentTaxonomyMap → SiteBlueprintTaxonomy → Clusters
         (through table)        (blueprint planning)

After (Simplified - Current):

Content ←→ ContentTaxonomy (many-to-many direct relationship)
         ↓
      Cluster (foreign key)

ContentTaxonomy Model

Location: backend/igny8_core/business/content/models.py

Fields:

• name - Term name (e.g., "Outdoor Living Design")
• slug - URL-safe version
• taxonomy_type - Choices: category, tag
• external_id - WordPress term_id for sync
• external_taxonomy - WordPress taxonomy slug (category, post_tag)
• description - Term description
• account, site, sector - Multi-tenancy fields

Relationship:

• Content.taxonomy_terms - ManyToManyField to ContentTaxonomy
• Categories/tags are AI-generated and linked directly to Content

---

How Content Taxonomy Works Now

Publishing Flow (IGNY8 → WordPress)

# In wordpress_publishing.py task

# STEP 4: Get categories from Content.taxonomy_terms
categories = [
    term.name 
    for term in content.taxonomy_terms.filter(taxonomy_type='category')
]

# Fallback to cluster if no taxonomy_terms
if not categories and content.cluster:
    categories.append(content.cluster.name)

# STEP 5: Get tags from taxonomy_terms + keywords
tags = [
    term.name 
    for term in content.taxonomy_terms.filter(taxonomy_type='tag')
]

# Add keywords as tags
if content.primary_keyword not in tags:
    tags.append(content.primary_keyword)
for keyword in content.secondary_keywords:
    if keyword not in tags:
        tags.append(keyword)

Data Flow

Keywords → Clusters → Ideas → Tasks → Content
                                       ├── taxonomy_terms (M2M)
                                       │   ├── Categories
                                       │   └── Tags
                                       ├── cluster (FK)
                                       ├── primary_keyword
                                       └── secondary_keywords
                                               ↓
                                       WordPress Publish
                                       ├── Categories (from taxonomy_terms + cluster)
                                       └── Tags (from taxonomy_terms + keywords)

---

Django Admin

ContentTaxonomy is registered in backend/igny8_core/modules/writer/admin.py:

• View at: /admin/writer/contenttaxonomy/
• Shows: name, taxonomy_type, slug, external_id, external_taxonomy, site, sector
• Searchable by: name, slug, external_taxonomy
• Filterable by: taxonomy_type, site, sector

---

Database Migration (PENDING)

Migration File: backend/igny8_core/business/site_building/migrations/0002_remove_blueprint_models.py

Status: Created but not applied (requires external PostgreSQL access)

Manual SQL Commands

Run these SQL commands directly on your production PostgreSQL database:

-- Drop foreign key constraints first
ALTER TABLE igny8_publishing_records 
  DROP CONSTRAINT IF EXISTS igny8_publishing_recor_site_blueprint_id_9f4e8c7a_fk_igny8_sit CASCADE;

ALTER TABLE igny8_deployment_records 
  DROP CONSTRAINT IF EXISTS igny8_deployment_recor_site_blueprint_id_3a2b7c1d_fk_igny8_sit CASCADE;

-- Drop blueprint tables
DROP TABLE IF EXISTS igny8_site_blueprint_taxonomies CASCADE;
DROP TABLE IF EXISTS igny8_site_blueprint_clusters CASCADE;
DROP TABLE IF EXISTS igny8_page_blueprints CASCADE;
DROP TABLE IF EXISTS igny8_site_blueprints CASCADE;

-- Drop SiteBuilder metadata tables
DROP TABLE IF EXISTS igny8_site_builder_business_types CASCADE;
DROP TABLE IF EXISTS igny8_site_builder_audience_profiles CASCADE;
DROP TABLE IF EXISTS igny8_site_builder_brand_personalities CASCADE;
DROP TABLE IF EXISTS igny8_site_builder_hero_imagery CASCADE;

-- Drop site_blueprint_id columns
ALTER TABLE igny8_publishing_records DROP COLUMN IF EXISTS site_blueprint_id CASCADE;
ALTER TABLE igny8_deployment_records DROP COLUMN IF EXISTS site_blueprint_id CASCADE;

-- Drop indexes
DROP INDEX IF EXISTS igny8_publishing_recor_site_blueprint_id_des_b7c4e5f8_idx;

-- Mark migration as applied
INSERT INTO django_migrations (app, name, applied)
VALUES ('site_building', '0002_remove_blueprint_models', NOW())
ON CONFLICT DO NOTHING;

---

Files Modified

Backend Python Files (24 files)

1. backend/igny8_core/business/site_building/models.py - All models removed
2. backend/igny8_core/business/site_building/admin.py - All admin classes removed
3. backend/igny8_core/business/publishing/models.py - Removed site_blueprint FK
4. backend/igny8_core/business/publishing/services/publisher_service.py - Removed publish_to_sites
5. backend/igny8_core/business/publishing/services/adapters/sites_renderer_adapter.py - Updated taxonomy usage
6. backend/igny8_core/business/content/services/metadata_mapping_service.py - Removed ContentTaxonomyMap
7. backend/igny8_core/business/linking/services/candidate_engine.py - Updated to M2M taxonomy
8. backend/igny8_core/business/optimization/services/analyzer.py - Updated taxonomy check
9. backend/igny8_core/modules/publisher/views.py - Removed blueprint actions
10. backend/igny8_core/modules/planner/serializers.py - Removed SiteBlueprintTaxonomy
11. backend/igny8_core/tasks/wordpress_publishing.py - Uses Content.taxonomy_terms
12. backend/igny8_core/urls.py - Removed site-builder URL
13. backend/igny8_core/settings.py - Removed site_builder from INSTALLED_APPS

Frontend TypeScript Files (3 files)

1. frontend/src/services/api.ts - Removed SiteBlueprint API functions
2. Removed: frontend/src/types/siteBuilder.ts
3. Removed: frontend/src/services/siteBuilder.api.ts
4. Removed: frontend/src/modules/siteBuilder/ directory

Migrations

1. Created: backend/igny8_core/business/site_building/migrations/0002_remove_blueprint_models.py

---

Testing Checklist

Backend Health Check

# Check if backend starts successfully
docker compose -f docker-compose.app.yml logs igny8_backend | grep -i "error\|exception"

# Should show no import errors

Taxonomy Workflow Test

1. Check ContentTaxonomy in Admin

   • Go to /admin/writer/contenttaxonomy/
   • Verify model is accessible
   • Check existing taxonomy terms

2. Test Content Creation

   # In Django shell
   from igny8_core.business.content.models import Content, ContentTaxonomy
   
   content = Content.objects.first()
   print(f"Taxonomy terms: {content.taxonomy_terms.count()}")
   print(f"Cluster: {content.cluster.name if content.cluster else 'None'}")
   

3. Test Publishing to WordPress

   • Create/select content with taxonomy_terms
   • Publish to WordPress from Review page
   • Verify categories and tags appear in WordPress
   • Check logs: tail -f backend/logs/publish-sync-logs/publish-sync.log

Expected Log Output

[2025-12-01 02:00:00] [INFO] [5-homeg8.com] STEP 4: Loading taxonomy terms...
[2025-12-01 02:00:00] [INFO] [5-homeg8.com] Found 1 categories from taxonomy_terms
[2025-12-01 02:00:00] [INFO] [5-homeg8.com] 📁 Category: 'Outdoor Living Design'
[2025-12-01 02:00:00] [INFO] [5-homeg8.com] ✅ TOTAL categories: 1

[2025-12-01 02:00:00] [INFO] [5-homeg8.com] STEP 5: Loading tags...
[2025-12-01 02:00:00] [INFO] [5-homeg8.com] 🏷️  Primary keyword: 'outdoor patio design'
[2025-12-01 02:00:00] [INFO] [5-homeg8.com] 🏷️  Secondary keywords: ['outdoor living spaces', 'outdoor kitchen design']
[2025-12-01 02:00:00] [INFO] [5-homeg8.com] ✅ TOTAL tags: 3

---

Remaining Legacy References

These files contain SiteBlueprint references in migrations only (historical data, safe to ignore):

• backend/igny8_core/business/content/migrations/0002_stage1_refactor_task_content_taxonomy.py
• backend/igny8_core/modules/writer/migrations/0001_initial.py
• backend/igny8_core/modules/planner/migrations/0002_initial.py
• backend/igny8_core/tasks/wordpress_publishing_backup.py (backup file)
• backend/igny8_core/tasks/wordpress_publishing_new.py (backup file)

---

Benefits of Simplified System

Before (Complex)

• 5 models: SiteBlueprint, PageBlueprint, SiteBlueprintCluster, SiteBlueprintTaxonomy, ContentTaxonomyMap
• 3-level indirection: Content → ContentTaxonomyMap → SiteBlueprintTaxonomy
• Blueprint planning layer for site building
• Difficult to understand taxonomy relationships

After (Simple)

• 1 model: ContentTaxonomy
• Direct M2M: Content ↔ ContentTaxonomy
• AI-generated categories/tags linked directly
• Clear taxonomy-content relationship in Django Admin

Performance Improvements

• Fewer database queries (eliminated ContentTaxonomyMap joins)
• Simpler ORM queries: content.taxonomy_terms.filter(taxonomy_type='category')
• Easier debugging and maintenance

---

Next Steps

1. Apply Database Migration

   • Run SQL commands on production PostgreSQL
   • Mark migration as applied in django_migrations table

2. Test Publishing Workflow

   • Publish content from Review page
   • Verify categories/tags in WordPress
   • Check sync logs for any errors

3. Monitor Logs

   • Backend: /data/app/igny8/backend/logs/publish-sync-logs/
   • WordPress: /wp-content/plugins/igny8-ai-os/logs/publish-sync-logs/

4. Update Documentation

   • Update SYSTEM-ARCHITECTURE doc to reflect simplified taxonomy
   • Remove SiteBuilder references from workflow docs

---

Rollback Plan (If Needed)

If issues arise, you can restore SiteBuilder functionality by:

1. Restore backup files:

   cd /data/app/igny8/backend/igny8_core/modules
   mv site_builder.backup site_builder
   

2. Uncomment in settings.py:

   'igny8_core.modules.site_builder.apps.SiteBuilderConfig',
   

3. Restore URL pattern in urls.py:

   path('api/v1/site-builder/', include('igny8_core.modules.site_builder.urls')),
   

4. Reverse database changes (restore from backup)

---

Contact & Support

If you encounter any issues during migration:

• Check logs in backend/logs/ and WordPress plugin logs/
• Review Django admin for ContentTaxonomy model
• Test publishing workflow step by step

Migration completed by: GitHub Copilot
Date: December 1, 2025
Version: IGNY8 v1.0 - SiteBuilder Removal