ai_qc/backend

Visual AI QC - AI-Powered Quality Control Platform

AI-driven visual quality control system for marketing materials, advertisements, and design assets

🚀 Overview

Visual AI QC is an intelligent quality control platform that uses advanced AI (OpenAI GPT-4 and Google Gemini) to automatically analyze visual content against brand guidelines, technical specifications, and design best practices. The system provides comprehensive feedback, scoring, and recommendations for improving visual assets across 33 specialized QC checks and 6 focused profiles.

✨ Key Features

• 🤖 AI-Powered Analysis: Leverages both OpenAI GPT-4 and Google Gemini for comprehensive visual analysis
• 📊 Real-Time Progress Tracking: Watch your analysis progress live with detailed step-by-step updates
• 🎯 Brand-Specific Profiles: Customizable analysis profiles for different brands and use cases
• 📋 Comprehensive Scoring: Weighted scoring system with detailed breakdowns and recommendations
• 📄 Multiple Output Formats: Generate results in HTML (visual reports) or JSON (data format)
• 🔄 Async Processing: Non-blocking analysis with progress tracking for better user experience
• ⚡ Parallel Processing: Batch-based parallel execution of QC checks for improved performance
• 📁 Reference Asset Integration: Upload and use brand guidelines to enhance analysis accuracy
• 🎨 Consumer-Focused Analysis: AI automatically focuses on consumer-facing visuals, ignoring production elements
• ⚡ Streamlined Workflow: Direct profile selection without unnecessary triage steps
• 🌐 Web Interface: User-friendly web UI for easy file uploads and result viewing
• 🔌 REST API: Full API access for programmatic integration
• 🔐 Enterprise Authentication: Secure Microsoft Azure AD authentication with MSAL/PKCE

🆕 Recent Improvements

September 2025 - Development & Production Environment Setup 🚀

Comprehensive Development/Production Workflow 🛠️

• Separate Environments: Complete isolation between development and production
  • Development: config/development.env, uploads-dev/, output-dev/
  • Production: config/production.env, uploads/, output/
  • Automatic Detection: System automatically selects environment based on ENVIRONMENT variable or config presence
• One-Command Operations: Streamlined scripts for all common tasks
  • ./scripts/run-local.sh: Start local development server with proper environment
  • ./scripts/test-system.sh: Comprehensive validation (syntax, imports, profiles, configs)
  • ./scripts/deploy-to-prod.sh: Full production deployment with backups and validation
• Enhanced Safety: Built-in protections and validations
  • Pre-deployment Testing: Automatic validation before production deployment
  • Backup Creation: Automatic backups before production updates
  • Rollback Capability: Easy rollback if deployment issues occur
  • Environment Validation: Checks for proper config files, Azure AD setup, and dependencies

Developer-Friendly Setup ⚡

• Quick Start: Single script gets development environment running
• Virtual Environment Support: Automatic detection and activation of Python virtual environments
• Dependency Management: Automatic installation/updating of requirements.txt
• Error Handling: Clear error messages and troubleshooting guidance
• Azure AD Integration: Separate development Azure AD app registration for localhost testing
• Backward Compatibility: Existing config.env setup still works as fallback

Deployment Automation 🚀

• Production Deployment: Single command deployment with comprehensive validation
• System Validation: Tests all critical components before deployment
  • Python syntax validation across all files
  • Core module import testing (api_server, llm_config, profile_config)
  • Authentication module testing (jwt_validator, auth_middleware)
  • All 6 QC profiles loading and validation
  • Brand guidelines database integrity
  • Configuration file validation
• Server Management: Automated server sync and service restart (configurable)
• Deployment Logs: Comprehensive logging of all deployment steps

August 2025 - Major System Overhaul 🚀

Streamlined Profile System 📊

• Consolidated Profiles: Reduced from 8+ profiles to 6 focused, purpose-built profiles
• General Check Profile: New streamlined 10-check profile for general-purpose analysis
  • 100-Point Scoring: Clean scoring system with even weighting (10% per check)
  • Essential Checks Only: Covers technical compliance, visual design, content, and marketing effectiveness
  • No Reference Assets Required: Works independently for quick analysis
• Brand-Specific Optimization: Maintained Unilever and Diageo profiles with specialized scoring logic
• Profile Cleanup: Removed redundant "All Checks", "General Key Visual", and "General Packaging" profiles

Fixed Scoring System 🧮

• Corrected 100-Point Scale: Fixed calculation bug where General Check profile showed 490/100 instead of correct scores
• Multi-Scale Support: System now handles different profile weight structures correctly
  • General Check (10.0 total weight) → Direct scoring for 100-point scale
  • Other profiles (1.0-1.2 total weight) → Scaled scoring for traditional systems
• Enhanced JSON Merging: Improved extraction of multiple JSON blocks from LLM responses
  • Combines metadata (face_present, new_present) with scoring data
  • Enables proper bonus check logic for brand profiles

December 2024 - Authentication & UX Enhancements 🚀

Enhanced Profile-Specific Scoring 📊

• Unilever Key Visual Profile: Implemented stringent zero-score logic for critical elements
  • Face Visibility: Automatically scores 0 when no face is detected in the image
  • New Visibility: Automatically scores 0 when no "NEW" text element is present
  • Face Gaze Direction: Automatically scores 0 when no face is available to analyze
• Smart Quality Control: Ensures essential brand elements receive appropriate scoring weight
• Profile-Aware Logic: Scoring rules apply specifically to Unilever profile without affecting others

Improved File Management & User Experience 📁

• Auto-Sorted Output Files: Latest analysis results automatically appear first in the saved files list
• Smart Refresh System: New files appear immediately after analysis completion without manual page refresh
• Progressive Detection: System tries multiple refresh attempts (1s, 3s, 5s) to catch files as soon as they're written
• Visual Feedback: New files highlighted with green background and "NEW" badge for 5 seconds
• Loading Indicators: Clear visual feedback showing "🔄 Checking for new files..." during refresh
• Intelligent Detection: Compares file counts to identify when new files are available

Enhanced Authentication Reliability 🔐

• Robust MSAL Integration: Fixed "Cannot read properties of undefined" authentication errors
• Initialization Validation: System checks MSAL library availability before attempting authentication
• Fallback CDN Support: Secondary CDN source if primary Microsoft CDN fails
• User-Friendly Error Handling: Clear error messages when authentication system unavailable
• State Tracking: Prevents authentication calls when system not properly initialized

Parallel Processing Architecture ⚡

• Batch-Based Execution: QC checks now run in parallel batches of 15 for dramatically improved performance
• Smart Batching Logic: Automatically organizes checks based on profile size (e.g., 11 checks = 1 batch, 25 checks = 2 batches)
• Enhanced Progress Tracking: Real-time batch progress with "Batch X of Y" indicators and individual check status
• Optimized Resource Usage: ThreadPoolExecutor manages concurrent API calls while respecting rate limits

Enhanced Analysis Workflow

• Removed Triage Steps: Analysis now uses your selected profile directly, reducing processing time
• Consumer-Focused Instructions: AI receives specific guidance to focus only on customer-facing visuals
• Production Element Filtering: Automatically ignores cut lines, registration marks, and technical elements

Reference Asset Integration

• Functional Reference Assets: Reference assets now actually enhance analysis (previously were ignored)
• Brand-Aware Analysis: Selected reference assets provide AI with brand-specific context and guidelines
• Visual Feedback: HTML reports clearly show when reference assets were used in analysis

Improved User Experience

• Streamlined Process: Reduced from 5 steps to 3 steps for faster analysis
• Better Progress Tracking: More accurate progress indicators throughout analysis
• Enhanced Reports: HTML reports include reference asset usage and more detailed metadata

🔐 Enterprise Authentication System

• Microsoft Azure AD Integration: Secure authentication using MSAL (Microsoft Authentication Library)
• PKCE Security Flow: Proof Key for Code Exchange ensures maximum security for single-page applications
• Popup-Based Login: Seamless "Sign In with Microsoft" experience without page redirects
• httpOnly Cookie Sessions: Secure server-side session management preventing XSS attacks
• Real-time Token Validation: Every API request validates tokens against Azure AD public keys
• Protected API Endpoints: All critical operations require authentication for security

🏗️ System Architecture

Visual AI QC Platform
├── 🔐 Authentication Layer (MSAL/Azure AD)
│   ├── JWT Token Validator (jwt_validator.py)
│   ├── Auth Middleware (auth_middleware.py)
│   └── httpOnly Cookie Sessions
├── 🌐 Web Interface (web_ui.html) - With authentication UI
├── 🚀 API Server (api_server.py) - Protected endpoints + parallel processing
├── ⚡ QC Analysis Engine (visual_qc_apps/) - Batch execution
├── 📋 Profile Management (profiles/)
├── 📁 Brand Guidelines DB (brand_guidelines/)
└── 📊 Output Management (output/)

🛠️ Quick Start

Prerequisites

• Python 3.8+
• OpenAI API Key
• Google AI API Key
• Microsoft Azure AD account (for authentication)
• Required Python packages (see requirements.txt)

Installation

New Environment Setup (Recommended) 🚀

1. Clone and Setup:

   cd Visual_AI_QC
   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   pip install -r requirements.txt
   

2. Configure Development Environment:

   # Copy environment template
   cp config/.env.template config/development.env
   
   # Edit config/development.env with your configuration:
   # OPENAI_API_KEY=your_openai_key_here
   # GOOGLE_API_KEY=your_google_key_here
   # AZURE_TENANT_ID=your_azure_tenant_id
   # AZURE_CLIENT_ID=your_dev_azure_client_id
   # SECRET_KEY=your-secret-key-here
   

3. Azure AD Setup (One-time):

   # Create separate Azure AD app registration for development
   # - Go to Azure Portal → Azure Active Directory → App registrations
   # - Create new registration: "Visual AI QC - Development"
   # - Set redirect URI: http://localhost:7183 (SPA type)
   # - Copy client ID to config/development.env
   

4. Start Development Server:

   ./scripts/run-local.sh
   

5. Access Web Interface: Open http://localhost:7183 in your browser

Legacy Setup (Still Supported)

1. Clone and Setup:

   cd Visual_AI_QC
   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   pip install -r requirements.txt
   

2. Configure Environment:

   cp config.env.example config.env
   # Edit config.env with your configuration:
   # OPENAI_API_KEY=your_openai_key_here
   # GOOGLE_API_KEY=your_google_key_here
   # AZURE_TENANT_ID=your_azure_tenant_id
   # AZURE_CLIENT_ID=your_azure_client_id
   # SECRET_KEY=your-secret-key-here
   

3. Start the Server:

   python api_server.py
   

4. Access Web Interface: Open http://localhost:7183 in your browser

📝 How to Perform an Analysis

Using the Web Interface

1. 🔐 Authentication (Required):

   • Navigate to http://localhost:7183
   • Click "Sign In with Microsoft" in the top-right corner
   • Complete Azure AD authentication in the popup window
   • Once authenticated, you'll see your user information displayed

2. 📁 Upload Your File:

   • Click the upload area or drag & drop your image
   • Supported formats: PNG, JPG, JPEG, GIF, WebP

3. ⚙️ Configure Analysis Settings:

   • Profile: Choose from available QC profiles (General, Brand-specific, etc.)
   • Output Mode: Select HTML Report (visual) or JSON Data (raw data)
   • AI Model: Choose between profile settings, OpenAI, or Gemini
   • Reference Asset: Optionally select a brand guideline for comparison

4. 🚀 Start Analysis:

   • Click "Analyze File"
   • Watch real-time progress updates showing batch processing in action
   • Progress shows "Batch X of Y" with individual check completion status

5. 📊 View Results:

   • Detailed analysis results appear in the interface
   • Overall score, grade, and individual check results
   • Download HTML report or access JSON data
   • Files saved automatically to /output folder

Analysis Steps Breakdown

When you start an analysis, the system performs these streamlined steps:

1. 🎯 Quality Control Analysis (5-95% complete)

   • Direct Profile Usage: Uses your selected QC profile immediately (no triage needed)
   • Consumer-Focused Analysis: AI focuses only on consumer-facing visuals, ignoring production elements
   • Reference Asset Integration: Incorporates selected reference assets into analysis prompts
   • Parallel Batch Execution: Runs QC checks in parallel batches of 15 with real-time progress updates
   • Comprehensive Evaluation: Each check analyzes specific aspects (logo visibility, text readability, etc.)
   • Brand-Aware Analysis: Uses profile-specific instructions and reference guidelines

2. 📊 Score Calculation (95% complete)

   • Calculates weighted overall score from individual check results
   • Determines letter grade (A, B, C, D, F)
   • Compiles comprehensive feedback and recommendations

3. 💾 Report Generation (100% complete)

   • Creates detailed HTML report (if HTML mode selected)
   • Saves results to output folder with reference asset tracking
   • Makes downloadable report available with full analysis details

🎯 Available QC Profiles

The system includes 6 focused QC profiles designed for different use cases:

1. General Check (10 checks, 100-point scale) 🎯

• Purpose: Streamlined general-purpose QC analysis
• Checks: aspect_ratio, background_contrast, call_to_action, curved_edges_digital, curved_edges_print, element_alignment, product_visibility, safety_area, text_readability, visual_elements_count
• Weighting: Even distribution (10% each)
• Requirements: No reference assets needed
• Best For: Quick comprehensive analysis of any visual content

Brand-Specific Profiles 🏢

2. Unilever Key Visual (15 checks, 120-point scale)

• Purpose: Unilever brand guidelines for key visual materials
• Special Logic: Bonus checks with zero-scoring for missing elements (face_visibility, new_visibility, face_gaze_direction)
• Requirements: Brand guidelines recommended
• Best For: Unilever marketing materials and key visuals

3. Unilever Packaging (17 checks)

• Purpose: Unilever packaging design standards
• Requirements: Brand guidelines recommended
• Best For: Unilever product packaging designs

4. Diageo Key Visual (11 checks)

• Purpose: Diageo brand guidelines for key visuals
• Requirements: Brand guidelines recommended
• Best For: Diageo advertising and marketing materials

5. Diageo Packaging (13 checks)

• Purpose: Diageo packaging design standards
• Requirements: Brand guidelines recommended
• Best For: Diageo product packaging and labeling

Specialized Profiles ♿

6. Inclusive Accessibility (2 checks)

• Purpose: Focused accessibility compliance
• Checks: accessibility, inclusive design
• Requirements: No reference assets needed
• Best For: Accessibility audits and inclusive design validation

Profile Selection Guidelines

• 🎯 General content analysis: Use General Check
• 🏢 Brand-specific analysis: Use appropriate brand profile (Unilever/Diageo)
• ♿ Accessibility focus: Use Inclusive Accessibility
• 🔄 Mixed requirements: Profiles can be combined in multi-profile analysis

🎨 Consumer-Focused Analysis

All profiles now include pre-analysis instructions that guide the AI to focus specifically on consumer-facing visuals:

What Gets Analyzed ✅

• Primary consumer-facing design elements
• Main/largest visual panels in multi-panel layouts
• Final product as it appears on shelf/in-market
• Assembled final product (for folded/die-cut layouts)

What Gets Ignored ❌

• Cut lines and registration marks
• Production guides and technical markings
• Color bars and printer calibration elements
• Technical text and file information
• Background production elements

Built-in Complexity Check

• Step 1: Count distinct visual elements (logos, images, text blocks, etc.)
• Step 2: Evaluate total element count
• Step 3: Flag designs with >4 elements as potentially too cluttered

This ensures analysis focuses on the actual customer experience rather than production technicalities.

⚡ Parallel Processing Performance

The system now uses batch-based parallel processing to dramatically improve analysis speed:

Performance Architecture

• Batch Size: Fixed at 15 QC checks per batch for optimal API usage
• Concurrent Execution: ThreadPoolExecutor manages parallel API calls within each batch
• Smart Batching: Automatically calculates batches based on enabled checks:
  • Diageo Key Visual (11 checks) → 1 batch
  • General Key Visual (21 checks) → 2 batches (15 + 6)
  • All Checks (34 checks) → 3 batches (15 + 15 + 4)

Progress Tracking Enhancements

• Batch Progress: "Processing batch 1 of 2" indicators
• Individual Check Status: Real-time completion tracking within batches
• Enhanced Visibility: See which checks are running in parallel
• Error Resilience: Individual check failures don't stop the batch

Performance Benefits

• Faster Analysis: Multiple checks run simultaneously instead of sequentially
• Better Resource Utilization: Optimized API usage with rate limiting consideration
• Improved User Experience: More detailed progress information with batch context
• Scalable Architecture: System adapts batch count based on profile complexity

🔍 Quality Control Checks

The system includes 33 specialized QC checks organized into categories:

Visual Design Checks

• Logo Visibility: Ensures brand logo is clearly visible and prominent
• Brand Assets Visibility: Verifies distinctive brand assets are recognizable
• Product Visibility: Checks if product imagery is clear and prominent
• Visual Hierarchy: Analyzes information hierarchy and visual flow
• Background Contrast: Evaluates contrast for readability and accessibility
• Face Visibility & Gaze Direction: Analyzes human faces in imagery
• Supporting Images: Evaluates relevance and quality of supporting visuals

Text & Typography Checks

• Text Readability: Ensures text is legible at appropriate viewing distances
• Call to Action: Evaluates effectiveness of CTA text and placement
• Lowercase Text: Checks adherence to brand typography guidelines
• Word Count: Validates appropriate amount of text content
• Imperative Verb: Ensures strong, action-oriented language

Layout & Composition Checks

• Element Alignment: Verifies proper alignment of design elements
• Visual Elements Count: Ensures appropriate number of visual elements
• Curved Edges: Checks for modern, curved design elements
• Aspect Ratio: Validates correct dimensions for intended use
• Safety Area: Ensures important content stays within safe zones
• New Visibility: Verifies "NEW" or promotional elements are prominent

Technical Checks

• Image Resolution: Validates appropriate resolution for intended use
• Color Format: Ensures correct color space (RGB/CMYK) for medium
• File Naming: Checks adherence to file naming conventions
• Layer Organization: Validates proper layer structure (for design files)
• Print Bleed: Ensures adequate bleed areas for print materials
• Crop Marks: Verifies presence of crop marks when required
• Animation Transitions: Evaluates smooth transitions (for animated content)
• Dark Mode Legibility: Tests readability in dark mode environments
• Responsiveness: Checks adaptability across different screen sizes

📊 Scoring System

Individual Check Scores

• Each QC check receives a score from 1-10
• 8-10: Excellent (Green)
• 5-7: Good/Adequate (Yellow)
• 1-4: Needs Improvement (Red)

Overall Score Calculation

• Weighted average of all individual check scores
• Weights defined in the selected profile
• Scaled to 100-point system for final score

Letter Grades

• A (85-100): Excellent - Ready for publication
• B (70-84): Good - Minor improvements recommended
• C (50-69): Adequate - Several improvements needed
• D (35-49): Poor - Significant rework required
• F (0-34): Fail - Major issues must be addressed

🗂️ Reference Asset Management

Adding Reference Assets

1. Navigate to Settings → Reference Assets
2. Click "Add New Reference Asset"
3. Upload brand guideline documents (PDF, images, text files)
4. Add descriptive title and brand tags
5. Reference assets become available for analysis

Using Reference Assets ✨

• Select Reference Assets: Choose from dropdown during analysis setup
• Automatic Integration: Selected assets are incorporated into every QC check prompt
• Brand-Specific Context: AI receives detailed brand guidelines and standards
• Enhanced Accuracy: Analysis becomes more brand-aware and consistent
• Visual Feedback: HTML reports show reference asset usage status
• Text Content Support: Text-based reference files (.txt, .md, .json) are read and included in prompts

Reference Asset Features

• Real Integration: Reference assets actually enhance analysis (no longer just stored)
• Per-Check Usage: Each QC check receives reference asset context
• File Type Support: Images (.png, .jpg), documents (.pdf), and text files (.txt, .md, .json)
• Content Limitation: Text content limited to 3000 characters for optimal prompt performance
• Error Handling: Graceful degradation when reference assets are unavailable

📁 File Management

Input Files

• Supported Formats: PNG, JPG, JPEG, GIF, WebP
• Upload Location: Files temporarily stored in /uploads/session_id/
• File Size: Recommended under 10MB for optimal performance

Output Files

• Location: /output/ directory
• Naming Convention: YYYYMMDD_HHMMSS_filename_report.html/data.json
• HTML Reports: Visual reports with expandable sections, scoring, and recommendations
• JSON Data: Raw analysis data for programmatic processing
• Retention: Files persist until manually deleted

🔐 Authentication & Security

Azure AD Authentication

The platform uses Microsoft Azure AD with MSAL (Microsoft Authentication Library) for enterprise-grade security:

🛡️ Security Features

• PKCE Flow: Proof Key for Code Exchange provides enhanced security for single-page applications
• Real-time Validation: Every API request validates JWT tokens against Azure AD public keys
• httpOnly Cookies: Authentication tokens stored in secure, XSS-resistant cookies
• Automatic Expiration: Tokens automatically expire and require re-authentication
• Protected Endpoints: All critical API operations require valid authentication

🔑 Authentication Flow

1. User Login: Click "Sign In with Microsoft" → Azure AD popup authentication
2. Token Exchange: MSAL exchanges authorization code for JWT tokens using PKCE
3. Server Validation: Python backend validates JWT signature against Azure AD JWKS
4. Session Creation: Valid tokens stored in httpOnly cookies with security flags
5. API Access: Subsequent requests include authentication cookie for validation

🚫 Protected Operations

The following operations require authentication:

• File Analysis: All analysis endpoints (/api/analyze, /api/start_analysis)
• Profile Management: Creating, updating, deleting QC profiles
• Brand Guidelines: Managing reference assets and brand guidelines
• File Processing: Direct file processing and triaged file operations

⚙️ Configuration Requirements

# Required in config.env
AZURE_TENANT_ID=your_azure_tenant_id    # Azure AD tenant
AZURE_CLIENT_ID=your_azure_client_id    # Registered application ID  
SECRET_KEY=your-secret-key-here         # Flask session security

🔧 Setup Instructions

1. Azure AD Application: Register your application in Azure AD as a Single Page Application (SPA)
2. Configure Redirect URIs: Add your application URLs to Azure AD app registration
3. Environment Variables: Set tenant ID and client ID in config.env
4. Dependencies: Ensure PyJWT and cryptography packages are installed

User Experience

• Seamless Login: Popup-based authentication without page redirects
• User Information: Display authenticated user's name and email
• Session Management: Easy sign-out with complete session cleanup
• Error Handling: Graceful handling of authentication failures and token expiration

🔌 API Integration

Key Endpoints

Authentication Endpoints

POST /auth/login

• Purpose: Validate MSAL token and create session
• Parameters: {"token": "jwt_token_from_msal"}
• Returns: Authentication status and user info

POST /auth/logout  

• Purpose: Clear authentication session
• Returns: Logout confirmation

GET /auth/status

• Purpose: Check current authentication status
• Returns: User info if authenticated, error if not

Analysis Endpoints

Start Analysis

POST /api/start_analysis

• Purpose: Start async analysis with progress tracking
• Authentication: Required (httpOnly cookie)
• Parameters: file, profile, mode, brand, reference_asset
• Returns: session_id for progress tracking

Check Progress

GET /api/progress/{session_id}

• Purpose: Get real-time analysis progress
• Returns: Current step, progress percentage, check details

Get Results

GET /api/progress/{session_id}

• Purpose: Retrieve completed analysis results
• Returns: Full analysis data when stage = 'complete'

Download Output

GET /output/{filename}

• Purpose: Download generated HTML/JSON reports
• Returns: File content for download

Example API Usage

import requests
import time

# Start analysis
with open('image.jpg', 'rb') as f:
    response = requests.post('http://localhost:7183/api/start_analysis', 
                           files={'file': f},
                           data={'profile': 'general', 'mode': 'html'})
    
session_id = response.json()['session_id']

# Poll for progress
while True:
    progress = requests.get(f'http://localhost:7183/api/progress/{session_id}')
    data = progress.json()['progress']
    
    if data['stage'] == 'complete':
        results = data['result']
        print(f"Analysis complete! Score: {results['summary']['overall_score']}")
        break
    else:
        print(f"Progress: Batch {data.get('current_batch', 1)} of {data.get('total_batches', 1)} - {data['completed_checks']}/{data['total_checks']} checks")
        time.sleep(2)

⚙️ Configuration & Customization

Creating Custom Profiles

1. Copy an existing profile from /profiles/
2. Modify checks, weights, and LLM preferences
3. Save with descriptive filename (e.g., my_brand.json)
4. Restart server to load new profile

Environment Configuration

Edit config.env:

OPENAI_API_KEY=your_openai_key
GOOGLE_API_KEY=your_google_key
FLASK_PORT=7183
DEBUG_MODE=false

Adding Custom QC Checks

1. Create new check in /visual_qc_apps/my_check/
2. Implement app.py with analysis logic
3. Register in profile configurations
4. Restart server to activate

🚨 Troubleshooting

Fixed Issues ✅

Analysis Stuck at "Step 1 of 1"

• ✅ RESOLVED: System now shows proper progress tracking with individual check names and accurate step counts

HTML Mode Saving JSON Files

• ✅ RESOLVED: Web UI correctly maintains output mode selection throughout analysis

"originalMode is not defined" JavaScript Error

• ✅ RESOLVED: Fixed JavaScript variable scoping issue in web UI

Reference Assets Not Working

• ✅ RESOLVED: Reference assets now actually enhance analysis prompts (previously were ignored)

"Cannot read properties of undefined (reading 'loginPopup')" Authentication Error

• ✅ RESOLVED: Added robust MSAL initialization checks and error handling

Saved Files Not Appearing After Analysis

• ✅ RESOLVED: Implemented smart refresh system with progressive retry mechanism

Saved Files Not Sorted by Date

• ✅ RESOLVED: Backend now automatically sorts files by creation date (newest first)

Manual Page Refresh Required for New Files

• ✅ RESOLVED: Automatic detection and display of new files with visual highlighting

Current Common Issues

Development Environment Issues

Config File Not Found

• Ensure config/development.env exists: ls -la config/
• Create from template: cp config/.env.template config/development.env
• Verify AZURE_CLIENT_ID is set correctly in development config

Development Server Won't Start

• Run with debug: ENVIRONMENT=development python api_server.py
• Check API keys in config/development.env (not config.env)
• Verify port 7183 is available: lsof -ti:7183
• Ensure virtual environment activated: source venv/bin/activate

Authentication Issues in Development

• Verify Azure AD redirect URI: http://localhost:7183
• Check AZURE_CLIENT_ID in config/development.env
• Ensure development Azure AD app registration exists
• Clear browser cache/cookies for localhost:7183

Script Permission Errors

• Make scripts executable: chmod +x scripts/*.sh
• Run from project root directory
• Check script paths are correct

General Issues

Server Won't Start

• Check API keys are set in appropriate config file
• New setup: config/development.env or config/production.env
• Legacy setup: config.env
• Verify port 7183 is not in use: lsof -ti:7183
• Check Python dependencies: pip install -r requirements.txt

Analysis Fails

• Verify image file is valid and under 10MB
• Check server logs for specific error messages
• Ensure selected profile exists and is valid
• Ensure reference asset exists if selected (system will continue without it)

Environment Detection Issues

• Check ENVIRONMENT variable: echo $ENVIRONMENT
• Verify config files exist: ls -la config/
• System falls back to config.env if new structure not found

Log Files

• Server Logs: server.log - General server activity
• Debug Logs: debug_mode.txt - Parameter debugging (if enabled)
• Error Logs: Check console output for detailed error messages

📚 Additional Documentation

Core Documentation

• Development/Production Setup: Complete guide for development and production environments (NEW ⭐)
• API Reference: Detailed API endpoint documentation
• Environment Setup: Comprehensive setup instructions
• Testing Guide: Testing procedures and examples
• Triage System: Automatic content type detection
• Profiles Guide: Profile configuration and customization

Deployment Documentation

• Migration Guide: Complete step-by-step migration to split frontend/backend structure (NEW 🚀)
• Migration Summary: Quick reference for deployment restructure (NEW 📋)
• Deployment Restructure: Detailed architecture and benefits explanation (NEW 🏗️)

🤝 Contributing

1. Fork the repository
2. Create feature branch: git checkout -b feature/amazing-feature
3. Commit changes: git commit -m 'Add amazing feature'
4. Push to branch: git push origin feature/amazing-feature
5. Open a Pull Request

📄 License

This project is proprietary software. All rights reserved.

🆘 Support

For technical support and questions:

• Review documentation in /docs/ directory
• Check existing issues and troubleshooting guide
• Contact the development team for enterprise support

---

Visual AI QC Platform - Ensuring quality through intelligent automation 🎯✨