# Unified HM QC Platform - Deployment Checklist

## Prerequisites

### 1. System Requirements
- Python 3.9 or higher
- ffmpeg (required for video processing)
  ```bash
  # macOS
  brew install ffmpeg

  # Ubuntu/Debian
  sudo apt-get install ffmpeg

  # Windows
  # Download from https://ffmpeg.org/download.html
  ```

- chromaprint (optional, for audio fingerprinting)
  ```bash
  # macOS
  brew install chromaprint

  # Ubuntu/Debian
  sudo apt-get install libchromaprint-tools
  ```

### 2. Environment Setup

**Step 1: Recreate Virtual Environment**
```bash
cd /Users/nickviljoen/Desktop/HM_QC_Bitbucket/hm_ai_qc_report_tool

# Remove old venv if exists
rm -rf venv

# Create new venv
python3 -m venv venv

# Activate venv
source venv/bin/activate  # macOS/Linux
# OR
venv\Scripts\activate     # Windows
```

**Step 2: Install Dependencies**
```bash
pip install --upgrade pip
pip install -r requirements.txt
```

**Step 3: Configure Environment Variables**

Create/update `.env` file:
```bash
# Flask Configuration
SECRET_KEY=<generate-random-key>
FLASK_ENV=development  # or production
HOST=0.0.0.0
PORT=7183
DEBUG=True  # Set to False in production

# Azure AD Authentication
AZURE_TENANT_ID=e519c2e6-bc6d-4fdf-8d9c-923c2f002385
AZURE_CLIENT_ID=9079054c-9620-4757-a256-23413042f1ef

# Box.com Configuration
BOX_CONFIG_PATH=config/box_config.json
BOX_REPORT_FOLDER_ID=133295752718

# Database
DATABASE_PATH=database/qc_platform.db

# LLM Providers (NO HARDCODED KEYS - all from environment)
OPENAI_API_KEY=<your-openai-api-key>
ANTHROPIC_API_KEY=<your-anthropic-api-key>
# Optional: Azure OpenAI
AZURE_OPENAI_API_KEY=<your-azure-key>
AZURE_OPENAI_ENDPOINT=<your-endpoint>
# Optional: Google Gemini
GOOGLE_API_KEY=<your-google-key>
```

**Important:** Never commit `.env` to version control!

### 3. Directory Structure Verification

Ensure these directories exist:
```bash
mkdir -p database
mkdir -p uploads/hm_qc
mkdir -p uploads/video_qc
mkdir -p uploads/video_master
mkdir -p storage/reports/hm_qc
mkdir -p storage/reports/consolidated
mkdir -p data/fingerprints
mkdir -p data/masters
```

### 4. Database Initialization

```bash
# Initialize database
python3 -c "from app import create_app; from core.models.database import db; app = create_app(); app.app_context().push(); db.create_all(); print('Database initialized')"
```

## Integration Testing

### Test 1: Application Startup
```bash
python3 test_integration.py
```

Expected output:
- ✓ App created successfully
- ✓ All 4 blueprints registered (reporting, hm_qc, video_qc, video_master)
- ✓ Database connectivity
- ✓ Core services available
- ✓ Routes accessible

### Test 2: Manual Startup
```bash
python3 app.py
```

Expected output:
```
INFO:__main__:Database initialized
INFO:__main__:Authentication initialized
INFO:__main__:Reporting blueprint registered at /reporting
INFO:__main__:HM QC blueprint registered at /hm-qc
INFO:__main__:Video QC blueprint (BETA) registered at /video-qc
INFO:__main__:Video Master blueprint (BETA) registered at /video-master
INFO:__main__:Application initialized successfully
 * Running on http://0.0.0.0:7183
```

### Test 3: Web Interface Access

Open browser to: `http://localhost:7183`

**Test each tab:**
1. ✅ **Reporting Tab** (`/reporting`)
   - Search interface loads
   - Job number search works
   - Box.com reports displayed
   - Dashboard view works

2. ✅ **HM QC Tab** (`/hm-qc`)
   - Landing page displays
   - Upload interface works
   - File upload successful
   - Configure profile selection
   - Execute QC and view progress
   - Results with scores displayed

3. ✅ **Video QC (BETA) Tab** (`/video-qc`)
   - Landing page with BETA badge
   - Upload interface loads
   - Feature list displayed
   - BETA notice present

4. ✅ **Video Master (BETA) Tab** (`/video-master`)
   - Landing page with BETA badge
   - 4-tier system description
   - Upload and Masters links work
   - BETA notice present

### Test 4: Authentication Flow
1. Navigate to any protected route
2. Redirected to Azure AD login
3. After login, session persists across tabs
4. Logout clears session from all tabs

### Test 5: Tab Switching
1. Switch between tabs
2. Verify state preservation (using sessionStorage)
3. Verify active tab highlighting
4. Verify BETA badges displayed correctly

## Module-Specific Testing

### HM QC Module Testing

**Test Workflow:**
```bash
# 1. Upload PDF/image
# 2. Select profile (standard_pdf)
# 3. Configure checks (enable/disable)
# 4. Execute QC
# 5. View progress (SSE or polling)
# 6. View results with score (0-100)
# 7. Download HTML report
```

**Expected Output:**
- Overall score: 0-100
- Status: passed (90+), warning (70-89), failed (<70)
- Check breakdown with individual scores
- Recommendations for improvements

### Video QC Module Testing

**Current Status:** BETA structure only
- Landing page functional
- Upload interface ready
- Full execution workflow: Coming soon

### Video Master Module Testing

**Test Matching Engine (Python):**
```python
from modules.video_master.matching import VideoMatcher

# Initialize
matcher = VideoMatcher(
    data_dir="data",
    enable_ai_vision=True,
    use_akaze=True,
    use_metadata_filter=True
)

# Add masters
matcher.add_master("/path/to/master.mp4", "master_1")

# Match adaptation
matches = matcher.match_adaptation("/path/to/adaptation.mp4")

# Check results
for match in matches:
    print(f"Master: {match['master_id']}")
    print(f"Confidence: {match['confidence_score']}/100")
    print(f"Method: {match['matching_method']}")
```

**Expected Output:**
- Stage 0: Metadata filtering reduces candidates
- Tier 1: Perceptual hash matching
- Tier 2: AKAZE verification (if enabled)
- Tier 3: AI Vision (only if needed)
- Match results with 0-100 confidence scores

### Reporting Module Testing

**Test Consolidation:**
1. Run HM QC on a PDF with job number "12345"
2. Navigate to Reporting tab
3. Search for "12345"
4. Verify both Box.com and HM QC reports appear
5. Verify source badges ("HM QC", "Box")
6. Test export functionality

## Performance Benchmarks

### HM QC Performance
- Simple filename check: <1 second
- AI-powered quality check: 2-5 seconds (depends on LLM)
- Full profile execution: 5-15 seconds (2 checks)

### Video Master Performance
- Stage 0 (metadata): <1 second
- Tier 1 (perceptual hash): 5-10 seconds for 50 masters
- Tier 2 (AKAZE): 5-10 seconds per candidate (top 5)
- Tier 3 (AI Vision): 3-5 seconds per comparison

### Expected Cost (AI Vision)
- GPT-4o: ~$0.006 per video comparison
- Smart triggering: Only used when needed (saves ~97%)

## Security Checklist

✅ **NO hardcoded API keys** - All from environment variables
✅ **httpOnly cookies** - Session tokens not accessible via JavaScript
✅ **Azure AD JWT validation** - Proper signature verification
✅ **Input validation** - File upload size limits, type checking
✅ **CORS configuration** - Appropriate for production
✅ **Secret key** - Random, not committed to git

## Troubleshooting

### Issue: Database locked
**Solution:** Check that no other process is using the database
```bash
lsof database/qc_platform.db
```

### Issue: ffmpeg not found
**Solution:** Install ffmpeg system-wide
```bash
brew install ffmpeg  # macOS
```

### Issue: LLM API errors
**Solution:** Verify API keys in `.env`
```bash
echo $OPENAI_API_KEY  # Should show your key
```

### Issue: Box.com authentication fails
**Solution:** Verify `config/box_config.json` exists and is valid

### Issue: Import errors
**Solution:** Verify virtual environment is activated and dependencies installed
```bash
which python  # Should show venv path
pip list | grep Flask  # Should show Flask installed
```

## Production Deployment

### Option 1: Gunicorn (Recommended)
```bash
gunicorn -c gunicorn_config.py wsgi:app
```

### Option 2: Docker (Future)
```bash
# Dockerfile to be created
docker build -t hm-qc-platform .
docker run -p 7183:7183 hm-qc-platform
```

## Backup & Recovery

### Database Backup
```bash
cp database/qc_platform.db database/qc_platform_backup_$(date +%Y%m%d).db
```

### Fingerprint Backup
```bash
tar -czf data_backup_$(date +%Y%m%d).tar.gz data/
```

## Monitoring

### Health Check Endpoint
```bash
curl http://localhost:7183/health
```

Expected response:
```json
{
  "status": "healthy",
  "timestamp": "2026-02-02T...",
  "box_connected": true
}
```

### Log Monitoring
```bash
tail -f logs/app.log  # If logging to file configured
```

## Success Criteria

✅ All 4 tabs accessible
✅ BETA labels displayed on Video QC and Video Master
✅ Authentication works across tabs
✅ HM QC complete workflow functional
✅ Reporting consolidation works (Box + HM QC)
✅ Video Master matching engine operational
✅ No hardcoded API keys
✅ Scoring system returns 0-100 scores
✅ Progress tracking works
✅ Tab state preservation works

---

**Platform Status:** ✅ **READY FOR DEPLOYMENT**
- All modules integrated
- AI_QC improvements applied
- Security hardened
- Documentation complete