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:
```javascript
// Automatically detects if running at / or /ai_qc/
const BASE_PATH = getBasePath();
fetch(`${BASE_PATH}api/profiles`, ...);
```

## Deployment Steps Overview

### 1. Deploy Backend
```bash
# 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
```bash
# On server
sudo cp frontend/index.html /var/www/html/ai_qc/
```

### 3. Configure Web Server
```bash
# 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
```bash
# 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

- [x] Created `frontend/` directory
- [x] Moved `web_ui.html` → `frontend/index.html`
- [x] Created frontend README
- [x] Created `backend/` directory
- [x] Copied all Python files to backend
- [x] Copied all application directories to backend
- [x] Copied configuration files to backend
- [x] Created backend deployment README
- [x] 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.