ai_qc/FOLDER_STRUCTURE.md

Visual AI QC - Frontend/Backend Folder Structure

Overview

The Visual AI QC application has been reorganized into separate frontend and backend folders for cleaner deployment and better separation of concerns.

Directory Structure

ai_qc/
├── frontend/                    # Web interface (to deploy to web root)
│   ├── index.html              # Single-page application
│   └── README.md               # Frontend deployment guide
│
├── backend/                     # Application backend (to deploy to /opt/)
│   ├── api_server.py           # Main Flask API server
│   ├── run_api_server.py       # Production WSGI wrapper
│   ├── llm_config.py           # LLM configuration
│   ├── profile_config.py       # Profile management
│   ├── jwt_validator.py        # JWT authentication
│   ├── auth_middleware.py      # Auth middleware
│   ├── brand_guidelines_db.py  # Brand guidelines DB
│   │
│   ├── visual_qc_apps/         # 33 QC check modules
│   ├── profiles/               # 6 QC profile configurations
│   ├── brand_guidelines/       # Reference assets storage
│   ├── config/                 # Environment configs
│   ├── scripts/                # Deployment scripts
│   ├── uploads/                # File upload storage
│   ├── uploads-dev/            # Dev upload storage
│   ├── output/                 # Generated reports
│   ├── output-dev/             # Dev generated reports
│   │
│   ├── requirements.txt        # Python dependencies
│   ├── ai_qc.service          # Systemd service config
│   ├── apache_config.conf     # Apache configuration
│   ├── BACKEND_README.md      # Backend deployment guide
│   └── ... (all documentation)
│
└── ... (original files remain for reference)

Deployment Mapping

Frontend → Web Root

frontend/index.html  →  /var/www/html/ai_qc/index.html

Purpose: Serve the web interface to users

Backend → /opt/

backend/*  →  /opt/ai_qc/*

Purpose: Run the application backend as a service

What Goes Where?

Frontend Directory (109 KB)

• Single File: index.html (renamed from web_ui.html)
• Purpose: User interface, authentication, file uploads, results display
• No Server Required: Can be served by Apache/Nginx directly
• Smart Path Detection: Automatically adapts to deployment location

Backend Directory (All Python Code & Data)

• Python Files: All .py files including:

  • api_server.py - Main Flask application
  • run_api_server.py - Production server wrapper
  • llm_config.py - LLM API interactions
  • profile_config.py - Profile management
  • Authentication modules
  • Helper scripts

• Application Directories:

  • visual_qc_apps/ - 33 QC check modules
  • profiles/ - 6 profile configurations
  • brand_guidelines/ - Reference assets
  • config/ - Environment configurations
  • scripts/ - Deployment automation

• Data Directories:

  • uploads/ & uploads-dev/ - Uploaded files
  • output/ & output-dev/ - Generated reports

• Configuration Files:

  • requirements.txt - Python dependencies
  • ai_qc.service - Systemd service
  • apache_config.conf - Web server config
  • config.env - Environment variables

• Documentation: All .md files

File Statistics

Frontend

• Total Files: 2 files (index.html + README.md)
• Total Size: ~113 KB
• Self-Contained: No dependencies, loads MSAL from CDN

Backend

• Python Files: 8 main modules
• QC Check Modules: 33 specialized checks
• Profile Configurations: 6 JSON files
• Total Components: 100+ files including documentation

Key Features of This Structure

✅ Separation of Concerns

• Frontend handles UI/UX only
• Backend handles all business logic
• Clear boundaries between components

✅ Security

• Backend code not in web-accessible directory
• Frontend cannot access sensitive configuration
• Production data separate from web root

✅ Deployment Flexibility

• Frontend can be updated without backend restart
• Backend can be updated without frontend changes
• Can easily scale to separate servers if needed

✅ Standard Practice

• Matches industry best practices
• Follows patterns used by other apps on server:
  • /opt/veo3/backend/
  • /opt/voice2text/
  • /opt/justeight/

How They Connect

Communication Flow

User Browser
    ↓
Frontend (index.html)
    ↓ HTTP Requests
Apache/Nginx (Reverse Proxy)
    ↓ http://localhost:7183/api
Backend (Flask on port 7183)
    ↓
QC Analysis Engine

API Communication

The frontend makes API calls to the backend:

• /api/profiles - Get available profiles
• /api/start_analysis - Start analysis
• /api/progress/{id} - Check progress
• /api/output_files - List reports
• /auth/login - Authenticate
• And more...

No Configuration Changes Needed!

The frontend already has smart base path detection:

// Automatically detects if running at / or /ai_qc/
const BASE_PATH = getBasePath();
fetch(`${BASE_PATH}api/profiles`, ...);

Deployment Steps Overview

1. Deploy Backend

# On server
rsync -av backend/ user@server:/opt/ai_qc/
cd /opt/ai_qc
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Configure and start service
sudo cp ai_qc.service /etc/systemd/system/
sudo systemctl enable ai_qc
sudo systemctl start ai_qc

2. Deploy Frontend

# On server
sudo cp frontend/index.html /var/www/html/ai_qc/

3. Configure Web Server

# Apache
sudo cp backend/apache_config.conf /etc/apache2/sites-available/ai_qc.conf
sudo a2ensite ai_qc.conf
sudo systemctl reload apache2

4. Test

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

# Test frontend
curl http://your-domain.com/

# Test in browser
open http://your-domain.com/

Benefits of This Structure

1. Security 🔒

• Backend code not accessible from web root
• Environment variables and secrets isolated
• Better permission control

2. Maintainability 🛠️

• Clear separation makes updates easier
• Can update frontend without backend restart
• Independent testing possible

3. Scalability 📈

• Easy to move backend to different server
• Can add multiple frontend instances
• Load balancing ready

4. Standard Practice ✅

• Industry-standard architecture
• Matches server's existing patterns
• Easier for new developers to understand

5. Deployment 🚀

• Simple rsync deployment
• Clear deployment targets
• Easy rollback if needed

Migration Checklist

• Created frontend/ directory
• Moved web_ui.html → frontend/index.html
• Created frontend README
• Created backend/ directory
• Copied all Python files to backend
• Copied all application directories to backend
• Copied configuration files to backend
• Created backend deployment README
• Verified all files present
• Test deployment locally (if desired)
• Deploy to server (follow MIGRATION_GUIDE.md)

Next Steps

1. Review Documentation

   • Read frontend/README.md for frontend deployment
   • Read backend/BACKEND_README.md for backend deployment
   • Read MIGRATION_GUIDE.md for complete server migration

2. Test Locally (Optional)

   • Start backend from backend/ directory
   • Serve frontend from frontend/ directory
   • Verify communication works

3. Deploy to Server

   • Follow MIGRATION_GUIDE.md step-by-step
   • Use MIGRATION_CHECKLIST.md to track progress
   • Monitor logs after deployment

Important Notes

Original Files Preserved

The original files in the root directory are unchanged. The frontend/ and backend/ directories are copies prepared for deployment. This allows you to:

• Keep the current working setup
• Test the new structure
• Deploy when ready
• Rollback if needed

Path Configuration

The backend already uses relative paths by default:

• uploads/ and output/ are relative
• Only need to update config/production.env for absolute paths
• No code changes required!

Frontend Auto-Detection

The frontend automatically detects its deployment location:

• Works at root: http://domain.com/
• Works in subdirectory: http://domain.com/ai_qc/
• No configuration changes needed!

Questions?

• Frontend deployment: See frontend/README.md
• Backend deployment: See backend/BACKEND_README.md
• Complete migration: See MIGRATION_GUIDE.md
• Quick reference: See MIGRATION_SUMMARY.md
• Day-of-migration: Use MIGRATION_CHECKLIST.md

---

Ready to Deploy! 🚀 You now have a clean, organized structure ready for production deployment.