ai_qc/backend/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:

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:

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:

  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

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