ai_qc/README.md

Visual AI QC - AI-Powered Quality Control Platform

AI-driven visual quality control for marketing materials and design assets using OpenAI GPT-4o and Google Gemini 2.5 Pro. Analyzes images and video against brand guidelines through 75 QC checks, 14 profiles, serving 8 clients.

Work in backend/ Directory

All development and production code is in the backend/ directory.

Directory Structure

ai_qc/
+-- backend/                  # MAIN APPLICATION
|   +-- api_server.py         # Flask application
|   +-- llm_config.py         # LLM configuration (GPT-4o, Gemini 2.5 Pro)
|   +-- ocr_measurement.py    # Tesseract OCR layout measurements
|   +-- profile_config.py     # Profile management
|   +-- client_config.py      # Client configuration (8 clients)
|   +-- pdf_processor.py      # PDF brand guideline processing
|   +-- media_plan_processor.py # Excel media plan parsing
|   +-- usage_tracker.py      # Usage tracking and cost estimation
|   +-- visual_qc_apps/       # QC check modules (75 checks)
|   +-- profiles/             # QC profile configurations (14 profiles)
|   +-- brand_guidelines/     # Reference assets and guidelines DB
|   +-- scripts/              # Deployment and testing scripts
|   +-- config/               # Environment configs
|   +-- uploads/              # File uploads (production)
|   +-- output/               # Generated reports (production)
|   +-- uploads-dev/          # File uploads (development)
|   +-- output-dev/           # Generated reports (development)
|   +-- usage_logs/           # Usage tracking JSONL logs
|   +-- media_plans/          # Uploaded media plans
|   +-- web_ui.html           # Web interface
|   +-- README.md             # Full documentation
|   +-- CLAUDE.md             # Development guide
|
+-- frontend/                 # Frontend-only deployment (optional)
+-- CLAUDE.md                 # Top-level development guide
+-- README.md                 # This file

Quick Start

Local Development

cd backend/
./scripts/run-local.sh
# Access at http://localhost:7183

Deploying to Dev / Prod

Code changes ship through Bitbucket branches (develop → dev server, tagged releases on main → prod server). Deploys are run manually on each server:

ssh <server>
cd /opt/ai_qc
backend/scripts/deploy.sh dev              # dev — pulls latest develop
backend/scripts/deploy.sh prod v1.2.0      # prod — checks out a specific tag
backend/scripts/deploy.sh dev --dry-run    # preview without applying
backend/scripts/rollback.sh last           # revert the most recent deploy
backend/scripts/health-check.sh            # quick "is it alive?"

See backend/CLAUDE.md for the full environment / branch / deploy reference.

Environments

Env	URL	Branch	Status
Local	http://localhost:7183	any	For active development
Dev	https://optical-dev.oliver.solutions/ai_qc/	develop	Live
Prod	https://optical-prod.oliver.solutions/ai_qc/	main (tagged)	Not yet stood up

Clients

Diageo, Unilever, L'Oreal, Amazon, Boots, Dow Jones, Honda, General

Capabilities

• Image QC: 75 checks across brand compliance, typography, layout, accessibility
• Video QC: Native Gemini video analysis (visual quality, brand consistency, text legibility, pacing)
• OCR Measurements: Tesseract pixel-level data for margin and alignment checks
• PDF Guidelines: Multi-page PDF upload with automatic LLM summarization
• Media Plans: Excel media plan parsing with asset spec validation
• Enterprise Auth: Azure AD with MSAL/PKCE and silent token refresh
• User Access Control: Default-deny per-user client access with admin grant/revoke and audit log
• Admin Panel: Usage analytics, user tracking, cost estimation, access management
• Profile Versioning: Automatic version control on profile edits

Documentation

• Full Documentation: See backend/README.md
• Development Guide: See backend/CLAUDE.md
• Deployment Guide: See backend/DEV_PROD_SETUP.md