igny8/docs/SITES_DECISION_GUIDE.md

# Sites Container - Keep vs Remove Decision Guide

**Version:** 1.0  
**Date:** November 29, 2025

---

## Decision Tree

```
Do you need Site Builder & Sites Renderer features?
│
├─ NO → Remove everything (Option A: Full Removal)
│   ├─ Delete /sites/ folder
│   ├─ Delete /site-builder/ folder  
│   ├─ Remove backend modules
│   ├─ Remove database tables
│   └─ Clean up all references
│
└─ YES → Do you need separate container?
    │
    ├─ NO → Merge into frontend (Option B: Integration)
    │   ├─ Copy files to /frontend/
    │   ├─ Update routes in App.tsx
    │   ├─ Remove /sites/ container
    │   └─ Keep backend modules
    │
    └─ YES → Keep current setup (Option C: No Changes)
        ├─ Keep /sites/ container running
        ├─ Keep separate ports (8021, 8024)
        └─ Maintain current architecture
```

---

## Option A: Full Removal (No Site Features)

### When to Choose
- ✅ You don't need site blueprint creation
- ✅ You don't need public site rendering
- ✅ You only need WordPress publishing (direct to WP)
- ✅ You want minimal feature set

### What Gets Removed

#### Frontend
```bash
# Remove folders
rm -rf /sites/
rm -rf /site-builder/
rm -rf /frontend/src/modules/siteBuilder/
rm -rf /frontend/src/pages/Sites/  # if exists
rm -rf /frontend/src/components/sites/  # site-specific only

# Remove from docker-compose
# Delete igny8_sites service
```

#### Backend
```bash
# Remove modules
rm -rf backend/igny8_core/modules/site_builder/
rm -rf backend/igny8_core/modules/publisher/  # Only if not using WP publish

# Remove business logic
rm -rf backend/igny8_core/business/site_building/
rm -rf backend/igny8_core/business/publishing/  # Be careful - WP uses this

# Update settings.py - remove from INSTALLED_APPS
# 'igny8_core.modules.site_builder',
```

#### Database
```sql
-- Drop tables (CAREFUL - NO UNDO)
DROP TABLE site_builder_siteblueprint CASCADE;
DROP TABLE site_builder_sitepage CASCADE;
DROP TABLE site_builder_taxonomy CASCADE;
DROP TABLE site_builder_cluster_blueprints CASCADE;
-- etc.
```

#### URLs
```python
# In backend/igny8_core/urls.py
# Remove:
# path('api/v1/site-builder/', include('igny8_core.modules.site_builder.urls')),
# path('api/v1/publisher/sites/<int:site_id>/definition/', ...)
```

### Files to Update

| File | Changes |
|------|---------|
| `docker-compose.app.yml` | Remove igny8_sites service |
| `backend/igny8_core/settings.py` | Remove site_builder from INSTALLED_APPS |
| `backend/igny8_core/urls.py` | Remove site-builder URL patterns |
| `frontend/src/App.tsx` | Remove site-related routes |
| `frontend/src/components/sidebar/AppSidebar.tsx` | Remove site builder menu |
| `frontend/package.json` | Remove site-builder dependencies (if any) |
| `docs/MASTER_REFERENCE.md` | Update architecture section |

### Impact
- ❌ No site blueprint creation
- ❌ No public site rendering
- ✅ WordPress publishing still works (if using direct WP API)
- ✅ Smaller codebase
- ✅ Fewer containers
- ✅ Simpler deployment

### Rollback Difficulty
🔴 **HARD** - Database tables deleted, requires full backup restore

---

## Option B: Merge Into Frontend (Recommended)

### When to Choose
- ✅ You need site builder features
- ✅ You need public site rendering
- ✅ You want simpler deployment
- ✅ You want unified authentication
- ✅ Sites are internal or low-traffic

### What Changes

#### Keep These (Backend)
```
backend/igny8_core/
├── modules/
│   ├── site_builder/     ✅ KEEP
│   └── publisher/        ✅ KEEP
├── business/
│   ├── site_building/    ✅ KEEP
│   └── publishing/       ✅ KEEP
└── Database tables       ✅ KEEP ALL
```

#### Move These (Frontend)
```
/sites/src/               → /frontend/src/pages/Sites/
/sites/src/builder/       → /frontend/src/pages/Sites/Builder/
/sites/src/utils/         → /frontend/src/utils/siteRenderer/
```

#### Delete These
```
/sites/ folder (after copying)
/site-builder/ folder
/frontend/src/modules/siteBuilder/ (empty)
igny8_sites Docker container
```

### Files to Update

| File | Type | Changes |
|------|------|---------|
| `frontend/src/App.tsx` | **UPDATE** | Add site builder & renderer routes |
| `frontend/src/services/siteRenderer.api.ts` | **CREATE** | Site renderer API client |
| `frontend/vite.config.ts` | **UPDATE** | Add SITES_DATA_PATH env |
| `docker-compose.app.yml` | **UPDATE** | Remove igny8_sites, update igny8_frontend |
| `backend/igny8_core/settings.py` | **VERIFY** | CORS settings (minor) |

### Step-by-Step Guide
📖 **See:** [SITES_REMOVAL_GUIDE.md](./SITES_REMOVAL_GUIDE.md) - Complete instructions

### Impact
- ✅ Site builder still works (routes change)
- ✅ Public site rendering still works (routes change)
- ✅ Backend unchanged (100% compatible)
- ⚠️ Public site URLs change (update links)
- ✅ Fewer containers (simpler deployment)
- ✅ Unified authentication

### Rollback Difficulty
🟡 **MEDIUM** - Can restore from backup, backend unchanged

---

## Option C: Keep Separate Container

### When to Choose
- ✅ You need performance isolation for public sites
- ✅ You want to scale sites independently
- ✅ You have high-traffic public sites
- ✅ You want different deployment schedules
- ✅ Current setup works fine

### What Changes
**Nothing!** Keep current architecture.

### Files to Update
**None** - No changes needed

### Maintenance
- Keep `/sites/` folder
- Keep `igny8_sites` container running
- Keep port 8024 accessible
- Maintain separate Docker image

### Impact
- ✅ No migration risk
- ✅ Performance isolation
- ✅ Independent scaling
- ❌ More containers to manage
- ❌ More complex deployment

### Rollback Difficulty
🟢 **EASY** - Already the current state

---

## Comparison Matrix

| Aspect | Option A: Full Removal | Option B: Merge to Frontend | Option C: Keep Separate |
|--------|----------------------|---------------------------|------------------------|
| **Containers** | 1 (frontend only) | 2 (frontend + backend) | 3 (frontend + sites + backend) |
| **Site Builder** | ❌ Removed | ✅ In frontend | ✅ In sites container |
| **Site Renderer** | ❌ Removed | ✅ In frontend | ✅ In sites container |
| **Backend API** | ❌ Removed | ✅ Kept | ✅ Kept |
| **Database** | ❌ Dropped | ✅ Kept | ✅ Kept |
| **Ports** | 8021 only | 8021 only | 8021, 8024 |
| **Deployment** | Simple | Simple | Complex |
| **Rollback** | Hard | Medium | Easy |
| **Performance** | N/A | Good | Best (isolated) |
| **Complexity** | Low | Medium | High |
| **Recommended For** | Minimal setup | Most users | High-traffic sites |

---

## Migration Difficulty

### Option A: Full Removal
```
Difficulty: ████████░░ 80%
Time: 6-8 hours
Risk: HIGH (data loss)
Rollback: HARD (requires backup)
```

**Steps:**
1. Backup database
2. Remove frontend folders
3. Remove backend modules
4. Drop database tables
5. Update URLs and settings
6. Remove Docker services
7. Update all documentation

### Option B: Merge to Frontend
```
Difficulty: ██████░░░░ 60%
Time: 5-6 hours
Risk: MEDIUM (UI changes)
Rollback: MEDIUM (restore backup)
```

**Steps:**
1. Backup files
2. Copy frontend files
3. Update routes
4. Update Docker config
5. Test functionality
6. Remove old container
7. Update documentation

### Option C: Keep Separate
```
Difficulty: ░░░░░░░░░░ 0%
Time: 0 hours
Risk: NONE
Rollback: N/A (no changes)
```

**Steps:**
1. None - keep current setup

---

## Recommendation by Use Case

### For Development/Testing
**→ Option B: Merge to Frontend**
- Simpler setup
- Easier debugging
- Fewer containers
- Faster iteration

### For Small Production (<100 sites)
**→ Option B: Merge to Frontend**
- Good performance
- Simpler deployment
- Lower resource usage
- Easier maintenance

### For Large Production (>100 sites, high traffic)
**→ Option C: Keep Separate**
- Performance isolation
- Independent scaling
- Better resource management
- Fault isolation

### For Minimal Setup (No site features needed)
**→ Option A: Full Removal**
- Smallest footprint
- Lowest complexity
- Minimal maintenance
- Only if truly not needed

---

## Red Flags - Don't Remove If:

🚫 **Don't choose Option A if:**
- You have existing site blueprints in database
- You're actively using site builder
- You publish to sites renderer (not just WordPress)
- You're unsure if you'll need it later

🚫 **Don't choose Option B if:**
- You have high-traffic public sites (>10k visits/day)
- You need to scale sites independently
- You have strict performance requirements
- You want to deploy sites on different infrastructure

🚫 **Don't choose Option C if:**
- You're struggling with too many containers
- You want simpler deployment
- You have low-traffic sites
- You value simplicity over isolation

---

## Safe Path Forward

### Recommended Approach

1. **Start with Option C** (Keep separate) ← You are here
2. **Evaluate for 30 days**
   - Monitor site traffic
   - Check resource usage
   - Assess deployment complexity
3. **If low traffic/simple needs** → **Move to Option B** (Merge)
4. **If high traffic/complex needs** → **Stay with Option C** (Keep separate)
5. **If features unused** → **Consider Option A** (Remove)

### Safe Testing Strategy

```bash
# 1. Test Option B in parallel (non-destructive)
# Keep sites container running on port 8024
# Deploy merged version on port 8021
# Compare functionality side-by-side

# 2. If Option B works well
# Switch traffic gradually
# Monitor for issues

# 3. After 30 days of stability
# Remove sites container (Option B complete)
```

---

## Decision Criteria

### Choose Option A (Full Removal) If:
- [ ] No existing site blueprints in database
- [ ] No plans to use site builder ever
- [ ] Only using WordPress publishing (direct)
- [ ] Want absolute minimal setup

### Choose Option B (Merge to Frontend) If:
- [x] Need site builder features
- [x] Have low-medium traffic sites
- [x] Want simpler deployment
- [x] Prefer fewer containers
- [x] Sites are mostly internal

### Choose Option C (Keep Separate) If:
- [ ] High-traffic public sites
- [ ] Need performance isolation
- [ ] Want independent scaling
- [ ] Current setup works well
- [ ] Have complex requirements

---

## Next Steps Based on Choice

### If Choosing Option A:
1. Read [SITES_REMOVAL_GUIDE.md](./SITES_REMOVAL_GUIDE.md) Section: "Full Removal"
2. Backup database completely
3. Export any site data you want to keep
4. Follow removal checklist
5. Test thoroughly

### If Choosing Option B:
1. Read [SITES_REMOVAL_GUIDE.md](./SITES_REMOVAL_GUIDE.md) - Full guide
2. Read [SITES_REMOVAL_QUICK_REFERENCE.md](./SITES_REMOVAL_QUICK_REFERENCE.md) - Quick commands
3. Backup files and database
4. Follow Phase 1-7 in guide
5. Test thoroughly before cleanup

### If Choosing Option C:
1. No action needed
2. Continue with current setup
3. Maintain both containers
4. Keep documentation updated

---

## Support Documentation

- **Full Removal & Integration Guide:** [SITES_REMOVAL_GUIDE.md](./SITES_REMOVAL_GUIDE.md)
- **Quick Reference:** [SITES_REMOVAL_QUICK_REFERENCE.md](./SITES_REMOVAL_QUICK_REFERENCE.md)
- **System Architecture:** [MASTER_REFERENCE.md](./MASTER_REFERENCE.md)
- **API Reference:** [API-COMPLETE-REFERENCE.md](./API-COMPLETE-REFERENCE.md)

---

**Recommendation:** Start with **Option C** (current state), evaluate needs, then move to **Option B** if appropriate.

**Last Updated:** November 29, 2025