ai_qc/MIGRATION_SUMMARY.md

# Visual AI QC Migration - Quick Summary

## What You Need to Know

### Why Split Frontend/Backend?

Your server already follows this pattern with other apps:
- `/opt/veo3/backend/` - Backend in opt
- `/opt/voice2text/` - Backend in opt
- `/opt/justeight/` - Backend in opt

This structure provides:
- ✅ **Better Security** - Backend code not in web root
- ✅ **Cleaner Separation** - Frontend and backend updates independent
- ✅ **Standard Practice** - Industry standard for web applications
- ✅ **Better Permissions** - Granular access control

### Current vs. New Structure

**Current:**
```
/var/www/html/ai_qc/  ← Everything here
├── web_ui.html (frontend)
├── api_server.py (backend)
├── visual_qc_apps/ (backend)
└── ... (all files mixed together)
```

**After Migration:**
```
/var/www/html/ai_qc/  ← Frontend only
└── index.html (renamed from web_ui.html)

/opt/ai_qc/  ← Backend only
├── api_server.py
├── run_api_server.py
├── visual_qc_apps/
├── profiles/
├── brand_guidelines/
├── uploads/
├── output/
└── ... (all Python code and data)
```

### Files Created for Migration

1. **`run_api_server.py`** - Production server wrapper (uses Waitress WSGI)
2. **`ai_qc.service`** - Systemd service configuration
3. **`apache_config.conf`** - Apache virtual host configuration
4. **`MIGRATION_GUIDE.md`** - Complete step-by-step instructions
5. **`requirements.txt`** - Updated with Waitress dependency

### Frontend Changes Required

**NONE!** Your `web_ui.html` already has smart base path detection:

```javascript
function getBasePath() {
    const path = window.location.pathname;
    if (path.includes('/ai_qc/')) {
        return path.substring(0, path.indexOf('/ai_qc/') + 7);
    }
    return '/';
}
```

This automatically detects if running at root (`/`) or subdirectory (`/ai_qc/`) and adjusts API calls accordingly.

### Backend Changes Required

Minimal! Just update file paths in `api_server.py` to use absolute paths:

```python
UPLOAD_FOLDER = '/opt/ai_qc/uploads'
OUTPUT_FOLDER = '/opt/ai_qc/output'
# etc.
```

### Migration Timeline

- **Preparation**: 10 minutes (backup, read guide)
- **Migration**: 15-20 minutes (follow MIGRATION_GUIDE.md)
- **Testing**: 10 minutes (verify all features work)
- **Total Downtime**: ~20-30 minutes

### Quick Migration Checklist

1. ✅ Read `MIGRATION_GUIDE.md` completely
2. ✅ Schedule maintenance window
3. ✅ Backup current deployment
4. ✅ Stop current service
5. ✅ Copy backend files to `/opt/ai_qc/`
6. ✅ Copy frontend to `/var/www/html/ai_qc/` (rename to index.html)
7. ✅ Update systemd service file
8. ✅ Update Apache configuration
9. ✅ Install waitress dependency
10. ✅ Test backend standalone
11. ✅ Start services
12. ✅ Test in browser
13. ✅ Enable service on boot

### Rollback Plan

If issues occur, rollback is simple:
1. Stop new service
2. Restore old Apache config
3. Rename old directory back
4. Start old service

Full instructions in `MIGRATION_GUIDE.md` → "Rollback Plan" section.

### What to Test After Migration

- [ ] Frontend loads (http://your-domain.com/)
- [ ] Authentication works (Microsoft sign-in)
- [ ] File upload works
- [ ] Analysis runs successfully
- [ ] Results display correctly
- [ ] Saved files list updates
- [ ] PDF downloads work
- [ ] All profiles load
- [ ] Brand guidelines work

### Need Help During Migration?

**Before Migration:**
- Read `MIGRATION_GUIDE.md` completely
- Test commands in Step 0 to understand current setup
- Verify backup is created successfully

**During Migration:**
- Follow steps sequentially - don't skip
- Test each step before moving to next
- Check logs if something fails:
  ```bash
  sudo journalctl -u ai_qc -n 50 --no-pager
  sudo tail -100 /var/log/apache2/ai_qc_error.log
  ```

**After Migration:**
- Monitor logs for first hour
- Test all major features
- Keep backup for 48 hours before deleting

### Common Issues and Solutions

| Issue | Cause | Solution |
|-------|-------|----------|
| Backend won't start | Permission denied | `sudo chown -R www-data:www-data /opt/ai_qc` |
| Module not found | Wrong Python environment | Check service file uses `/opt/ai_qc/venv/bin/python` |
| API not responding | Service not running | `sudo systemctl status ai_qc` |
| Frontend shows 404 | Apache config wrong | Check DocumentRoot path in Apache config |
| Uploads fail | Directory permissions | `sudo chmod 770 /opt/ai_qc/uploads` |

### Key Commands

```bash
# Check service status
sudo systemctl status ai_qc

# View logs (live)
sudo journalctl -u ai_qc -f

# Check Apache logs
sudo tail -f /var/log/apache2/ai_qc_error.log

# Test backend directly
curl http://localhost:7183/api/profiles

# Test through Apache
curl http://your-domain.com/api/profiles

# Restart service
sudo systemctl restart ai_qc

# Reload Apache
sudo systemctl reload apache2
```

### Files to Review Before Migration

1. **Read completely**: `MIGRATION_GUIDE.md`
2. **Understand**: `apache_config.conf` (your Apache setup)
3. **Review**: `ai_qc.service` (systemd service)
4. **Check**: `run_api_server.py` (server wrapper)

### Next Steps

1. **Read `MIGRATION_GUIDE.md`** - Complete step-by-step instructions
2. **Schedule maintenance window** - 30 minutes recommended
3. **Test in development** - If you have a dev server, test there first
4. **Execute migration** - Follow guide exactly
5. **Monitor and verify** - Test all features thoroughly

---

## Questions?

- **Where's the detailed guide?** → `MIGRATION_GUIDE.md`
- **What Apache config do I use?** → `apache_config.conf`
- **How do I start the service?** → See `ai_qc.service`
- **Need to rollback?** → `MIGRATION_GUIDE.md` → "Rollback Plan"