Complete PhotoGuard rebrand and API documentation

- Rebrand from 'Civic Photo Quality Control' to 'PhotoGuard'
- Convert UI theme to professional black/white/gray monochrome palette
- Add comprehensive OpenAPI 3.1 specification
- Implement interactive Swagger UI documentation (/api/docs)
- Add ReDoc API reference documentation (/api/redoc)
- Remove geographic validation and unrelated code
- Clean up project structure (removed 15+ unnecessary files)
- Update all descriptions to be generic and professional
- Add new API endpoints for documentation serving
- Update README with new branding and documentation links
- Version bump to 3.0.0

.dockerignore

@@ -0,0 +1,44 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Development
+.git/
+.gitignore
+.vscode/
+.idea/
+.DS_Store
+*.log
+
+# Storage (runtime generated)
+storage/temp/*
+storage/processed/*
+storage/rejected/*
+logs/*
+
+# Documentation & tests
+docs/
+tests/
+*.md
+CHANGELOG.md
+QUICK_START.md
+
+# CI/CD
+.github/
+
+# Local dev files
+api_test.py
+start_production.sh
+start_production.bat

.gitignore

@@ -75,11 +75,7 @@ dmypy.json
 .idea/
 .DS_Store
 Thumbs.db
-storage/temp/*
-storage/processed/*
-storage/rejected/*
-!storage/temp/.gitkeep
-!storage/processed/.gitkeep
-!storage/rejected/.gitkeep
-models/*.pt
-!models/.gitkeep
+# Auto-created directories (app creates these automatically)
+storage/
+logs/
+*.log

CHANGELOG.md

@@ -1,162 +0,0 @@
-# Changelog - Civic Photo Quality Control API
-
-All notable changes to this project will be documented in this file.
-
-## [2.0.0] - September 26, 2025
-
-### 🎉 Major Release - Production Ready
-
-#### Added
-- **Weighted Scoring System**: Intelligent partial credit validation
-  - Blur Detection: 25% weight
-  - Resolution Check: 25% weight
-  - Brightness Validation: 20% weight
-  - Exposure Analysis: 15% weight
-  - Metadata Extraction: 15% weight
-  - Pass threshold: 65% overall score
-
-- **Mobile-Optimized Validation Rules**:
-  - Blur threshold: 100 (down from 150)
-  - Brightness range: 50-220 (expanded from 90-180)
-  - Resolution: 800×600 minimum (down from 1024×1024)
-  - Metadata requirement: 15% (down from 30%)
-  - Exposure tolerance: Increased flexibility
-
-- **Comprehensive API Endpoints**:
-  - `GET /api/health` - System health check
-  - `POST /api/validate` - Primary image validation
-  - `GET /api/summary` - Processing statistics
-  - `GET /api/validation-rules` - Current thresholds
-  - `GET /api/test-api` - API information
-  - `POST /api/upload` - Legacy endpoint (deprecated)
-
-- **Complete Documentation Suite**:
-  - README.md - Comprehensive project overview
-  - QUICK_START.md - 60-second deployment guide
-  - docs/API_v2.md - Full API documentation
-  - docs/DEPLOYMENT.md - Production deployment guide
-  - docs/DEPLOYMENT_CHECKLIST.md - Step-by-step deployment
-
-#### Changed
-- **Acceptance Rate Improvement**: 16.67% → 35-40% (132% increase)
-- **Response Format**: New structured JSON with summary and detailed checks
-- **Configuration**: Centralized in config.py with comprehensive comments
-- **Error Handling**: Enhanced with detailed error messages and recommendations
-
-#### Improved
-- **Code Documentation**: Comprehensive docstrings and inline comments
-- **Configuration Clarity**: Detailed explanations of all validation rules
-- **Production Readiness**: Enhanced deployment scripts and logging
-- **Mobile Compatibility**: Optimized thresholds for smartphone photography
-
-#### Removed
-- Outdated test files (create_and_test.py, direct_test.py, etc.)
-- Windows-specific batch files
-- Duplicate configuration files (production.yaml, .env)
-- Obsolete API documentation (docs/API.md)
-
-### 📊 Performance Metrics
-
-- **Acceptance Rate**: 35-40% (target achieved)
-- **Processing Time**: <2 seconds per image
-- **API Response Time**: <500ms for health checks
-- **Supported Formats**: JPG, JPEG, PNG, BMP, TIFF
-- **Maximum File Size**: 32MB
-
-### 🔧 Technical Details
-
-#### Validation Components
-1. **Blur Detection** (25%)
-   - Method: Laplacian variance analysis
-   - Threshold: 100 minimum
-   - Levels: Poor (0-99), Acceptable (100-299), Excellent (300+)
-
-2. **Resolution Check** (25%)
-   - Minimum: 800×600 pixels (0.5MP)
-   - Recommended: 2+ megapixels
-   - Supports landscape and portrait orientations
-
-3. **Brightness Validation** (20%)
-   - Range: 50-220 pixel intensity
-   - Method: Histogram analysis
-   - Quality threshold: 60% minimum
-
-4. **Exposure Analysis** (15%)
-   - Dynamic range: 80-150 acceptable
-   - Clipping check: Max 2% clipped pixels
-   - Method: Pixel distribution analysis
-
-5. **Metadata Extraction** (15%)
-   - Required completeness: 15%
-   - Key fields: Timestamp, camera info, settings
-   - EXIF analysis with GPS validation
-
-### 🚀 Deployment
-
-#### Docker Deployment (Recommended)
-```bash
-docker-compose up -d
-```
-
-#### Manual Deployment
-```bash
-pip install -r requirements.txt
-python scripts/setup_directories.py
-python scripts/download_models.py
-gunicorn --bind 0.0.0.0:8000 --workers 4 production:app
-```
-
-### 📚 Documentation
-
-- **API Documentation**: Comprehensive endpoint documentation with examples
-- **Deployment Guide**: Step-by-step production deployment instructions
-- **Quick Start**: 60-second getting started guide
-- **Configuration Reference**: Detailed explanation of all settings
-
-### 🔒 Security
-
-- File type validation (images only)
-- Size limits enforced (32MB maximum)
-- Input sanitization on all uploads
-- Automatic temporary file cleanup
-- Environment variable secrets
-- No sensitive data in error responses
-
-### 🧪 Testing
-
-- Comprehensive API test suite (api_test.py)
-- Unit tests for individual components
-- Sample images for validation testing
-- Production testing checklist included
-
-### 📈 Future Enhancements
-
-- [ ] Real-time processing optimization
-- [ ] Advanced object detection integration
-- [ ] Batch processing capabilities
-- [ ] API rate limiting
-- [ ] Enhanced mobile UI
-- [ ] Multi-language support
-
----
-
-## [1.0.0] - Initial Release
-
-### Added
-- Basic image validation pipeline
-- Initial API endpoints
-- Development server configuration
-- Basic documentation
-
-### Known Issues (Resolved in v2.0)
-- Low acceptance rate (16.67%)
-- Strict validation rules not suitable for mobile
-- Limited documentation
-- No weighted scoring system
-
----
-
-**Version**: 2.0.0  
-**Status**: ✅ Production Ready  
-**Last Updated**: September 26, 2025  
-**Repository**: https://github.com/nitish-niraj/civic-photo-quality-control

Dockerfile

@@ -53,7 +53,7 @@ COPY --from=builder /usr/local/bin /usr/local/bin
 COPY . .
 
 # Create necessary directories
-RUN mkdir -p storage/temp storage/processed storage/rejected models
+RUN mkdir -p storage/temp storage/processed storage/rejected
 
 # Set ownership and permissions
 RUN chown -R app:app /app && \
@@ -62,15 +62,12 @@ RUN chown -R app:app /app && \
 # Switch to non-root user
 USER app
 
-# Download YOLO model if not present
-RUN python -c "from ultralytics import YOLO; YOLO('yolov8n.pt')" || true
-
 # Expose port
 EXPOSE 8000
 
 # Health check
 HEALTHCHECK --interval=30s --timeout=30s --start-period=60s --retries=3 \
-    CMD curl -f http://localhost:8000/api/health || exit 1
+    CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/api/health')" || exit 1
 
 # Production server command
-CMD ["gunicorn", "--bind", "0.0.0.0:8000", "--workers", "4", "--timeout", "120", "--access-logfile", "-", "--error-logfile", "-", "app:app"]
+CMD ["gunicorn", "--bind", "0.0.0.0:8000", "--workers", "4", "--timeout", "120", "--access-logfile", "-", "--error-logfile", "-", "production:app"]

QUICK_START.md

@@ -1,271 +0,0 @@
-# 🚀 Quick Production Deployment Guide
-
-**Civic Quality Control API v2.0** - Ready for immediate production deployment!
-
-## ⚡ 60-Second Deployment
-
-### **1. Quick Docker Deployment**
-```bash
-# Clone and build
-git clone <your-repo-url> civic_quality_app
-cd civic_quality_app
-
-# Set production environment
-export SECRET_KEY="your-production-secret-key-256-bit"
-
-# Deploy immediately
-docker-compose up -d
-
-# Verify deployment (should return "healthy")
-curl http://localhost:8000/api/health
-```
-
-### **2. Test Your Deployment**
-```bash
-# Test image validation
-curl -X POST -F 'image=@your_test_photo.jpg' \
-     http://localhost:8000/api/validate
-
-# Check acceptance rate (should be 35-40%)
-curl http://localhost:8000/api/summary
-```
-
-**✅ Production Ready!** Your API is now running at `http://localhost:8000`
-
----
-
-## 🎯 What You Get Out-of-the-Box
-
-### **✅ Mobile-Optimized Validation**
-- **35-40% acceptance rate** for quality mobile photos
-- **Weighted scoring system** with partial credit
-- **<2 second processing** per image
-- **5-component analysis**: blur, resolution, brightness, exposure, metadata
-
-### **✅ Complete API Suite**
-```bash
-GET  /api/health          # System status
-POST /api/validate        # Image validation (primary)
-GET  /api/summary         # Processing statistics  
-GET  /api/validation-rules # Current thresholds
-GET  /api/test-api        # API information
-POST /api/upload          # Legacy endpoint
-```
-
-### **✅ Production Features**
-- **Secure file handling** (32MB limit, format validation)
-- **Comprehensive error handling** 
-- **Automatic cleanup** of temporary files
-- **Detailed logging** and monitoring
-- **Mobile web interface** included
-
----
-
-## 📊 Current Performance Metrics
-
-| Metric | Value | Status |
-|--------|-------|--------|
-| **Acceptance Rate** | 35-40% | ✅ Optimized |
-| **Processing Time** | <2 seconds | ✅ Fast |
-| **API Endpoints** | 6 functional | ✅ Complete |
-| **Mobile Support** | Full compatibility | ✅ Ready |
-| **Error Handling** | Comprehensive | ✅ Robust |
-
----
-
-## 🔧 Environment Configuration
-
-### **Required Environment Variables**
-```bash
-# Minimal required setup
-export SECRET_KEY="your-256-bit-production-secret-key"
-export FLASK_ENV="production"
-
-# Optional optimizations
-export MAX_CONTENT_LENGTH="33554432"  # 32MB
-export WORKERS="4"                    # CPU cores
-```
-
-### **Optional: Custom Validation Rules**
-The system is already optimized for mobile photography, but you can adjust in `config.py`:
-
-```python
-VALIDATION_RULES = {
-    "blur": {"min_score": 100},           # Laplacian variance
-    "brightness": {"range": [50, 220]},   # Pixel intensity  
-    "resolution": {"min_megapixels": 0.5}, # 800x600 minimum
-    "exposure": {"min_score": 100},       # Dynamic range
-    "metadata": {"min_completeness_percentage": 15}  # EXIF data
-}
-```
-
----
-
-## 🌐 Access Your Production API
-
-### **Primary Endpoints**
-- **Health Check**: `http://your-domain:8000/api/health`
-- **Image Validation**: `POST http://your-domain:8000/api/validate`
-- **Statistics**: `http://your-domain:8000/api/summary`
-- **Mobile Interface**: `http://your-domain:8000/mobile_upload.html`
-
-### **Example Usage**
-```javascript
-// JavaScript example
-const formData = new FormData();
-formData.append('image', imageFile);
-
-fetch('/api/validate', {
-  method: 'POST',
-  body: formData
-})
-.then(response => response.json())
-.then(data => {
-  if (data.success && data.data.summary.overall_status === 'PASS') {
-    console.log(`Image accepted with ${data.data.summary.overall_score}% score`);
-  }
-});
-```
-
----
-
-## 🔒 Production Security
-
-### **✅ Security Features Included**
-- **File type validation** (images only)
-- **Size limits** (32MB maximum)  
-- **Input sanitization** (all uploads validated)
-- **Temporary file cleanup** (automatic)
-- **Environment variable secrets** (externalized)
-- **Error message sanitization** (no sensitive data exposed)
-
-### **Recommended Additional Security**
-```bash
-# Setup firewall
-ufw allow 22 80 443 8000
-ufw enable
-
-# Use HTTPS in production (recommended)
-# Configure SSL certificate
-# Set up reverse proxy (nginx/Apache)
-```
-
----
-
-## 📈 Monitoring Your Production System
-
-### **Health Monitoring**
-```bash
-# Automated health checks
-*/5 * * * * curl -f http://your-domain:8000/api/health || alert
-
-# Performance monitoring  
-curl -w "%{time_total}" http://your-domain:8000/api/health
-
-# Acceptance rate tracking
-curl http://your-domain:8000/api/summary | jq '.data.acceptance_rate'
-```
-
-### **Log Monitoring**
-```bash
-# Application logs
-tail -f logs/app.log
-
-# Docker logs
-docker-compose logs -f civic-quality-app
-
-# System resources
-htop
-df -h
-```
-
----
-
-## 🚨 Quick Troubleshooting
-
-### **Common Issues & 10-Second Fixes**
-
-#### **API Not Responding**
-```bash
-curl http://localhost:8000/api/health
-# If no response: docker-compose restart civic-quality-app
-```
-
-#### **Low Acceptance Rate**  
-```bash
-# Check current rate
-curl http://localhost:8000/api/summary
-# System already optimized to 35-40% - this is correct for mobile photos
-```
-
-#### **Slow Processing**
-```bash
-# Check processing time
-time curl -X POST -F 'image=@test.jpg' http://localhost:8000/api/validate
-# If >3 seconds: increase worker count or check system resources
-```
-
-#### **Storage Issues**
-```bash
-df -h  # Check disk space
-# Clean temp files: find storage/temp -type f -mtime +1 -delete
-```
-
----
-
-## 📋 Production Deployment Variants
-
-### **Variant 1: Single Server**
-```bash
-# Simple single-server deployment
-docker run -d --name civic-quality \
-  -p 8000:8000 \
-  -e SECRET_KEY="your-key" \
-  civic-quality-app:v2.0
-```
-
-### **Variant 2: Load Balanced**
-```bash
-# Multiple instances with load balancer
-docker run -d --name civic-quality-1 -p 8001:8000 civic-quality-app:v2.0
-docker run -d --name civic-quality-2 -p 8002:8000 civic-quality-app:v2.0
-# Configure nginx/ALB to distribute traffic
-```
-
-### **Variant 3: Cloud Deployment**
-```bash
-# AWS/Azure/GCP
-# Use production Docker image: civic-quality-app:v2.0
-# Set environment variables via cloud console
-# Configure auto-scaling and load balancing
-```
-
----
-
-## 🎉 You're Production Ready!
-
-**Congratulations!** Your Civic Quality Control API v2.0 is now:
-
-✅ **Deployed and running**  
-✅ **Mobile-optimized** (35-40% acceptance rate)  
-✅ **High-performance** (<2 second processing)  
-✅ **Fully documented** (API docs included)  
-✅ **Production-hardened** (security & monitoring)  
-
-### **What's Next?**
-1. **Point your mobile app** to the API endpoints
-2. **Set up monitoring alerts** for health and performance  
-3. **Configure HTTPS** for production security
-4. **Scale as needed** based on usage patterns
-
-### **Support Resources**
-- **Full Documentation**: `docs/README.md`, `docs/API_v2.md`, `docs/DEPLOYMENT.md`
-- **Test Your API**: Run `python api_test.py`
-- **Mobile Interface**: Access at `/mobile_upload.html`
-- **Configuration**: Adjust rules in `config.py` if needed
-
----
-
-**Quick Start Guide Version**: 2.0  
-**Deployment Status**: ✅ **PRODUCTION READY**  
-**Updated**: September 25, 2025

README.md

@@ -1,6 +1,6 @@
-# Civic Quality Control API
+# PhotoGuard API
 
-A production-ready mobile photo validation system for civic documentation with intelligent quality control and comprehensive API endpoints.
+Professional image quality validation system with automated blur detection, brightness analysis, resolution checking, exposure verification, and metadata extraction.
 
 ## 🚀 Key Features
 
@@ -49,18 +49,20 @@ pip install -r requirements.txt
 ### Setup & Run
 
 ```bash
-# Setup directories and download models
-python scripts/setup_directories.py
-python scripts/download_models.py
-
-# Start development server
+# Start development server (creates storage directories automatically)
 python app.py
 
-# Access mobile interface
-# http://localhost:5000/mobile_upload.html
+# Access the web interface
+# http://localhost:5000
 ```
 
-## 📱 API Endpoints
+## � API Documentation
+
+### Interactive Documentation
+
+- **Swagger UI**: http://localhost:5000/api/docs - Interactive API testing interface
+- **ReDoc**: http://localhost:5000/api/redoc - Comprehensive API reference
+- **OpenAPI Spec**: http://localhost:5000/api/openapi.json - OpenAPI 3.1 specification
 
 ### Core Endpoints
 
@@ -140,17 +142,7 @@ GET /api/validation-rules
 ```
 Returns current validation thresholds and requirements.
 
-### Testing Endpoints
-
-#### 5. API Information  
-```bash
-GET /api/test-api
-```
 
-#### 6. Legacy Upload (Deprecated)
-```bash
-POST /api/upload
-```
 
 ## 🏗️ Production Deployment
 
@@ -266,8 +258,7 @@ civic_quality_app/
 │       ├── brightness_validation.py
 │       ├── exposure_check.py
 │       ├── resolution_check.py
-│       ├── metadata_extraction.py
-│       └── object_detection.py
+│       └── metadata_extraction.py
 │
 ├── storage/                    # File storage
 │   ├── temp/                  # Temporary uploads
@@ -366,14 +357,12 @@ For issues and improvements:
 ### Future Enhancements
 
 - [ ] Real-time processing optimization
-- [ ] Advanced object detection integration
-- [ ] GPS metadata validation
 - [ ] Batch processing capabilities
 - [ ] API rate limiting
 - [ ] Enhanced mobile UI
 
 ---
 
-**Version**: 2.0  
-**Last Updated**: September 25, 2025  
+**Version**: 3.0.0  
+**Last Updated**: November 3, 2025  
 **Production Status**: ✅ Ready for deployment

api_test.py

@@ -1,187 +0,0 @@
-#!/usr/bin/env python3
-"""
-API Test Script for Civic Quality Control App
-Demonstrates how to test the updated validation API endpoints.
-"""
-
-import requests
-import json
-import os
-import sys
-from pathlib import Path
-
-# Configuration
-API_BASE_URL = "http://localhost:5000/api"
-TEST_IMAGE_PATH = "storage/temp/7db56d0e-ff94-49ca-b61a-5f33469fe4af_IMG_20220629_174412.jpg"
-
-def test_health_endpoint():
-    """Test the health check endpoint."""
-    print("🔍 Testing Health Endpoint...")
-    try:
-        response = requests.get(f"{API_BASE_URL}/health")
-        print(f"Status Code: {response.status_code}")
-        print(f"Response: {json.dumps(response.json(), indent=2)}")
-        return response.status_code == 200
-    except Exception as e:
-        print(f"❌ Health check failed: {e}")
-        return False
-
-def test_validation_rules_endpoint():
-    """Test the validation rules endpoint."""
-    print("\n🔍 Testing Validation Rules Endpoint...")
-    try:
-        response = requests.get(f"{API_BASE_URL}/validation-rules")
-        print(f"Status Code: {response.status_code}")
-        if response.status_code == 200:
-            rules = response.json()
-            print("✅ Validation Rules Retrieved:")
-            print(json.dumps(rules, indent=2))
-        return response.status_code == 200
-    except Exception as e:
-        print(f"❌ Validation rules test failed: {e}")
-        return False
-
-def test_api_info_endpoint():
-    """Test the API information endpoint."""
-    print("\n🔍 Testing API Information Endpoint...")
-    try:
-        response = requests.get(f"{API_BASE_URL}/test-api")
-        print(f"Status Code: {response.status_code}")
-        if response.status_code == 200:
-            info = response.json()
-            print("✅ API Information Retrieved:")
-            print(f"API Version: {info['data']['api_version']}")
-            print(f"Available Endpoints: {len(info['data']['endpoints'])}")
-            print("\nEndpoints:")
-            for endpoint, description in info['data']['endpoints'].items():
-                print(f"  {endpoint}: {description}")
-        return response.status_code == 200
-    except Exception as e:
-        print(f"❌ API info test failed: {e}")
-        return False
-
-def test_image_validation_endpoint():
-    """Test the main image validation endpoint."""
-    print("\n🔍 Testing Image Validation Endpoint...")
-    
-    # Check if test image exists
-    if not os.path.exists(TEST_IMAGE_PATH):
-        print(f"❌ Test image not found: {TEST_IMAGE_PATH}")
-        print("Please ensure you have an image in the storage/temp folder or update TEST_IMAGE_PATH")
-        return False
-    
-    try:
-        # Prepare file for upload
-        with open(TEST_IMAGE_PATH, 'rb') as f:
-            files = {'image': f}
-            response = requests.post(f"{API_BASE_URL}/validate", files=files)
-        
-        print(f"Status Code: {response.status_code}")
-        
-        if response.status_code == 200:
-            result = response.json()
-            print("✅ Image Validation Completed!")
-            
-            # Extract key information
-            data = result['data']
-            summary = data['summary']
-            checks = data['checks']
-            
-            print(f"\n📊 Overall Status: {summary['overall_status'].upper()}")
-            print(f"📊 Overall Score: {summary['overall_score']}")
-            print(f"📊 Issues Found: {summary['issues_found']}")
-            
-            # Show validation results
-            print("\n📋 Validation Results:")
-            for check_type, check_result in checks.items():
-                if check_result:
-                    status = "✅ PASS" if check_result.get('status') == 'pass' else "❌ FAIL"
-                    reason = check_result.get('reason', 'unknown')
-                    print(f"  {check_type}: {status} - {reason}")
-            
-            # Show recommendations if any
-            if summary['recommendations']:
-                print(f"\n💡 Recommendations ({len(summary['recommendations'])}):")
-                for rec in summary['recommendations']:
-                    print(f"  - {rec}")
-                    
-        else:
-            print(f"❌ Validation failed with status {response.status_code}")
-            print(f"Response: {response.text}")
-            
-        return response.status_code == 200
-        
-    except Exception as e:
-        print(f"❌ Image validation test failed: {e}")
-        return False
-
-def test_summary_endpoint():
-    """Test the processing summary endpoint."""
-    print("\n🔍 Testing Summary Endpoint...")
-    try:
-        response = requests.get(f"{API_BASE_URL}/summary")
-        print(f"Status Code: {response.status_code}")
-        if response.status_code == 200:
-            summary = response.json()
-            print("✅ Processing Summary Retrieved:")
-            data = summary['data']
-            print(f"  Total Images Processed: {data.get('total_images', 0)}")
-            print(f"  Accepted Images: {data.get('total_processed', 0)}")
-            print(f"  Rejected Images: {data.get('total_rejected', 0)}")
-            print(f"  Acceptance Rate: {data.get('acceptance_rate', 0)}%")
-        return response.status_code == 200
-    except Exception as e:
-        print(f"❌ Summary test failed: {e}")
-        return False
-
-def main():
-    """Run all API tests."""
-    print("🚀 Starting Civic Quality Control API Tests")
-    print("=" * 50)
-    
-    # Check if server is running
-    try:
-        requests.get(API_BASE_URL, timeout=5)
-    except requests.exceptions.ConnectionError:
-        print("❌ Server not running! Please start the server first:")
-        print("   python app.py")
-        print("   Or: python production.py")
-        sys.exit(1)
-    
-    # Run tests
-    tests = [
-        ("Health Check", test_health_endpoint),
-        ("Validation Rules", test_validation_rules_endpoint),
-        ("API Information", test_api_info_endpoint),
-        ("Image Validation", test_image_validation_endpoint),
-        ("Processing Summary", test_summary_endpoint),
-    ]
-    
-    passed = 0
-    total = len(tests)
-    
-    for test_name, test_func in tests:
-        print(f"\n{'='*20} {test_name} {'='*20}")
-        if test_func():
-            passed += 1
-            print(f"✅ {test_name} PASSED")
-        else:
-            print(f"❌ {test_name} FAILED")
-    
-    # Final results
-    print("\n" + "="*50)
-    print(f"📊 Test Results: {passed}/{total} tests passed")
-    
-    if passed == total:
-        print("🎉 All tests passed! API is working correctly.")
-    else:
-        print("⚠️  Some tests failed. Check the output above for details.")
-    
-    print("\n💡 API Usage Examples:")
-    print(f"  Health Check: curl {API_BASE_URL}/health")
-    print(f"  Get Rules: curl {API_BASE_URL}/validation-rules")
-    print(f"  Validate Image: curl -X POST -F 'image=@your_image.jpg' {API_BASE_URL}/validate")
-    print(f"  Get Summary: curl {API_BASE_URL}/summary")
-
-if __name__ == "__main__":
-    main()

app/__init__.py

@@ -1,40 +1,47 @@
-from flask import Flask
+from flask import Flask, render_template
 import os
 
-def create_app(config_name='default'):
-    # Set template and static folders relative to project root
-    app = Flask(__name__, 
-                template_folder='../templates',
-                static_folder='../static')
 
-    # Load configuration
-    from config import config
-    app.config.from_object(config[config_name])
+def create_app(config_name: str = 'default') -> Flask:
+    """Application factory that wires configuration, blueprints, and assets."""
+    app = Flask(
+        __name__,
+        template_folder='../templates',
+        static_folder='../static'
+    )
 
-    # Enable CORS if available
+    # Load configuration class by name with graceful fallback to default.
+    from config import config as config_map
+    config_class = config_map.get(config_name, config_map['default'])
+    app.config.from_object(config_class)
+
+    # Enable CORS when the optional dependency is available.
     try:
-        from flask_cors import CORS
+        from flask_cors import CORS  # type: ignore
         CORS(app)
     except ImportError:
         print("Warning: Flask-CORS not installed, CORS disabled")
 
-    # Create necessary directories
+    # Ensure required storage directories exist so uploads succeed at runtime.
     directories = [
         app.config['UPLOAD_FOLDER'],
-        'storage/processed',
-        'storage/rejected',
-        'models'
+        app.config.get('PROCESSED_FOLDER', 'storage/processed'),
+        app.config.get('REJECTED_FOLDER', 'storage/rejected')
     ]
 
     for directory in directories:
         os.makedirs(directory, exist_ok=True)
-        # Create .gitkeep files
         gitkeep_path = os.path.join(directory, '.gitkeep')
         if not os.path.exists(gitkeep_path):
             open(gitkeep_path, 'a').close()
 
-    # Register blueprints
+    # Register API blueprint.
     from app.routes.upload import upload_bp
     app.register_blueprint(upload_bp, url_prefix='/api')
 
+    @app.route('/')
+    def index():
+        """Serve the main quality control interface."""
+        return render_template('index.html')
+
     return app

app/api_spec.py

@@ -0,0 +1,542 @@
+"""
+PhotoGuard API - OpenAPI 3.1 Specification
+===========================================
+Complete API specification for PhotoGuard image quality validation system.
+"""
+
+OPENAPI_SPEC = {
+    "openapi": "3.1.0",
+    "info": {
+        "title": "PhotoGuard API",
+        "version": "3.0.0",
+        "description": "Professional image quality validation system with automated blur detection, brightness analysis, resolution checking, exposure verification, and metadata extraction",
+        "contact": {
+            "name": "PhotoGuard API Support"
+        }
+    },
+    "servers": [
+        {
+            "url": "/api",
+            "description": "API Server"
+        }
+    ],
+    "tags": [
+        {
+            "name": "Image Validation",
+            "description": "Core image quality validation endpoints"
+        },
+        {
+            "name": "System Information",
+            "description": "System status and configuration endpoints"
+        }
+    ],
+    "paths": {
+        "/validate": {
+            "post": {
+                "tags": ["Image Validation"],
+                "summary": "Validate Image Quality",
+                "description": "Upload an image and receive comprehensive quality validation results including blur detection, brightness analysis, resolution check, exposure verification, and metadata extraction",
+                "operationId": "validate_image",
+                "requestBody": {
+                    "required": True,
+                    "content": {
+                        "multipart/form-data": {
+                            "schema": {
+                                "$ref": "#/components/schemas/ImageUpload"
+                            }
+                        }
+                    }
+                },
+                "responses": {
+                    "200": {
+                        "description": "Validation completed successfully",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/ValidationResponse"
+                                }
+                            }
+                        }
+                    },
+                    "400": {
+                        "description": "Bad request - Invalid file or missing parameters",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/ErrorResponse"
+                                }
+                            }
+                        }
+                    },
+                    "413": {
+                        "description": "File too large - Maximum 16MB",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/ErrorResponse"
+                                }
+                            }
+                        }
+                    },
+                    "500": {
+                        "description": "Internal server error",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/ErrorResponse"
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        },
+        "/validation-rules": {
+            "get": {
+                "tags": ["System Information"],
+                "summary": "Get Validation Rules",
+                "description": "Retrieve the current validation rules and thresholds used by the system",
+                "operationId": "get_validation_rules",
+                "responses": {
+                    "200": {
+                        "description": "Validation rules retrieved successfully",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/ValidationRulesResponse"
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        },
+        "/summary": {
+            "get": {
+                "tags": ["System Information"],
+                "summary": "Get Processing Summary",
+                "description": "Retrieve aggregate validation statistics including total images processed, pass/fail counts, and average scores",
+                "operationId": "get_summary",
+                "responses": {
+                    "200": {
+                        "description": "Processing summary retrieved successfully",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/SummaryResponse"
+                                }
+                            }
+                        }
+                    },
+                    "500": {
+                        "description": "Internal server error",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/ErrorResponse"
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        },
+        "/health": {
+            "get": {
+                "tags": ["System Information"],
+                "summary": "Health Check",
+                "description": "Check if the API service is running and healthy",
+                "operationId": "health_check",
+                "responses": {
+                    "200": {
+                        "description": "Service is healthy",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/HealthResponse"
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    },
+    "components": {
+        "schemas": {
+            "ImageUpload": {
+                "type": "object",
+                "required": ["image"],
+                "properties": {
+                    "image": {
+                        "type": "string",
+                        "format": "binary",
+                        "description": "Image file to validate (jpg, jpeg, png, bmp, tiff). Maximum size: 16MB"
+                    }
+                }
+            },
+            "ValidationResponse": {
+                "type": "object",
+                "properties": {
+                    "success": {
+                        "type": "boolean",
+                        "description": "Whether the request was processed successfully",
+                        "example": True
+                    },
+                    "message": {
+                        "type": "string",
+                        "description": "Response message",
+                        "example": "Image validation completed"
+                    },
+                    "data": {
+                        "type": "object",
+                        "properties": {
+                            "summary": {
+                                "type": "object",
+                                "properties": {
+                                    "overall_status": {
+                                        "type": "string",
+                                        "enum": ["pass", "fail"],
+                                        "description": "Overall validation result"
+                                    },
+                                    "overall_score": {
+                                        "type": "number",
+                                        "format": "float",
+                                        "description": "Overall weighted quality score (0-100)",
+                                        "example": 78.5
+                                    },
+                                    "issues_found": {
+                                        "type": "array",
+                                        "items": {
+                                            "type": "string"
+                                        },
+                                        "description": "List of quality issues detected"
+                                    },
+                                    "recommendations": {
+                                        "type": "array",
+                                        "items": {
+                                            "type": "string"
+                                        },
+                                        "description": "Recommendations for improving image quality"
+                                    }
+                                }
+                            },
+                            "checks": {
+                                "type": "object",
+                                "properties": {
+                                    "blur": {
+                                        "$ref": "#/components/schemas/BlurCheck"
+                                    },
+                                    "brightness": {
+                                        "$ref": "#/components/schemas/BrightnessCheck"
+                                    },
+                                    "resolution": {
+                                        "$ref": "#/components/schemas/ResolutionCheck"
+                                    },
+                                    "exposure": {
+                                        "$ref": "#/components/schemas/ExposureCheck"
+                                    },
+                                    "metadata": {
+                                        "$ref": "#/components/schemas/MetadataCheck"
+                                    }
+                                }
+                            }
+                        }
+                    }
+                }
+            },
+            "BlurCheck": {
+                "type": "object",
+                "properties": {
+                    "status": {
+                        "type": "string",
+                        "enum": ["pass", "fail"],
+                        "description": "Blur check result"
+                    },
+                    "score": {
+                        "type": "number",
+                        "format": "float",
+                        "description": "Laplacian variance score (higher = sharper)",
+                        "example": 245.8
+                    },
+                    "threshold": {
+                        "type": "number",
+                        "format": "float",
+                        "description": "Minimum acceptable blur score",
+                        "example": 100.0
+                    },
+                    "quality_percentage": {
+                        "type": "number",
+                        "format": "float",
+                        "description": "Quality score as percentage (0-100)",
+                        "example": 85.5
+                    }
+                }
+            },
+            "BrightnessCheck": {
+                "type": "object",
+                "properties": {
+                    "status": {
+                        "type": "string",
+                        "enum": ["pass", "fail"],
+                        "description": "Brightness check result"
+                    },
+                    "mean_brightness": {
+                        "type": "number",
+                        "format": "float",
+                        "description": "Mean pixel intensity (0-255)",
+                        "example": 145.3
+                    },
+                    "acceptable_range": {
+                        "type": "array",
+                        "items": {
+                            "type": "integer"
+                        },
+                        "description": "Acceptable brightness range",
+                        "example": [50, 220]
+                    },
+                    "quality_percentage": {
+                        "type": "number",
+                        "format": "float",
+                        "description": "Quality score as percentage (0-100)",
+                        "example": 92.0
+                    }
+                }
+            },
+            "ResolutionCheck": {
+                "type": "object",
+                "properties": {
+                    "status": {
+                        "type": "string",
+                        "enum": ["pass", "fail"],
+                        "description": "Resolution check result"
+                    },
+                    "width": {
+                        "type": "integer",
+                        "description": "Image width in pixels",
+                        "example": 1920
+                    },
+                    "height": {
+                        "type": "integer",
+                        "description": "Image height in pixels",
+                        "example": 1080
+                    },
+                    "megapixels": {
+                        "type": "number",
+                        "format": "float",
+                        "description": "Total megapixels",
+                        "example": 2.07
+                    },
+                    "quality_percentage": {
+                        "type": "number",
+                        "format": "float",
+                        "description": "Quality score as percentage (0-100)",
+                        "example": 100.0
+                    }
+                }
+            },
+            "ExposureCheck": {
+                "type": "object",
+                "properties": {
+                    "status": {
+                        "type": "string",
+                        "enum": ["pass", "fail"],
+                        "description": "Exposure check result"
+                    },
+                    "dynamic_range": {
+                        "type": "number",
+                        "format": "float",
+                        "description": "Dynamic range (difference between max and min pixel values)",
+                        "example": 185.5
+                    },
+                    "clipping_percentage": {
+                        "type": "number",
+                        "format": "float",
+                        "description": "Percentage of clipped pixels (pure white or black)",
+                        "example": 0.5
+                    },
+                    "quality_percentage": {
+                        "type": "number",
+                        "format": "float",
+                        "description": "Quality score as percentage (0-100)",
+                        "example": 88.0
+                    }
+                }
+            },
+            "MetadataCheck": {
+                "type": "object",
+                "properties": {
+                    "status": {
+                        "type": "string",
+                        "enum": ["pass", "fail"],
+                        "description": "Metadata check result"
+                    },
+                    "completeness": {
+                        "type": "number",
+                        "format": "float",
+                        "description": "Metadata completeness percentage",
+                        "example": 66.7
+                    },
+                    "fields_found": {
+                        "type": "integer",
+                        "description": "Number of metadata fields found",
+                        "example": 4
+                    },
+                    "fields_required": {
+                        "type": "integer",
+                        "description": "Total number of expected metadata fields",
+                        "example": 6
+                    },
+                    "extracted_data": {
+                        "type": "object",
+                        "description": "Extracted EXIF metadata",
+                        "properties": {
+                            "timestamp": {
+                                "type": "string",
+                                "description": "Image capture timestamp"
+                            },
+                            "camera_make_model": {
+                                "type": "string",
+                                "description": "Camera make and model"
+                            },
+                            "gps": {
+                                "type": "object",
+                                "properties": {
+                                    "latitude": {
+                                        "type": "number",
+                                        "format": "float"
+                                    },
+                                    "longitude": {
+                                        "type": "number",
+                                        "format": "float"
+                                    }
+                                }
+                            }
+                        }
+                    }
+                }
+            },
+            "ValidationRulesResponse": {
+                "type": "object",
+                "properties": {
+                    "success": {
+                        "type": "boolean",
+                        "example": True
+                    },
+                    "message": {
+                        "type": "string",
+                        "example": "Current validation rules"
+                    },
+                    "data": {
+                        "type": "object",
+                        "properties": {
+                            "blur": {
+                                "type": "object",
+                                "description": "Blur detection rules (25% weight)"
+                            },
+                            "brightness": {
+                                "type": "object",
+                                "description": "Brightness validation rules (20% weight)"
+                            },
+                            "resolution": {
+                                "type": "object",
+                                "description": "Resolution check rules (25% weight)"
+                            },
+                            "exposure": {
+                                "type": "object",
+                                "description": "Exposure analysis rules (15% weight)"
+                            },
+                            "metadata": {
+                                "type": "object",
+                                "description": "Metadata extraction rules (15% weight)"
+                            }
+                        }
+                    }
+                }
+            },
+            "SummaryResponse": {
+                "type": "object",
+                "properties": {
+                    "success": {
+                        "type": "boolean",
+                        "example": True
+                    },
+                    "message": {
+                        "type": "string",
+                        "example": "Processing summary retrieved"
+                    },
+                    "data": {
+                        "type": "object",
+                        "properties": {
+                            "total_processed": {
+                                "type": "integer",
+                                "description": "Total number of images processed",
+                                "example": 150
+                            },
+                            "passed": {
+                                "type": "integer",
+                                "description": "Number of images that passed validation",
+                                "example": 98
+                            },
+                            "failed": {
+                                "type": "integer",
+                                "description": "Number of images that failed validation",
+                                "example": 52
+                            },
+                            "average_score": {
+                                "type": "number",
+                                "format": "float",
+                                "description": "Average quality score across all processed images",
+                                "example": 72.5
+                            }
+                        }
+                    }
+                }
+            },
+            "HealthResponse": {
+                "type": "object",
+                "properties": {
+                    "success": {
+                        "type": "boolean",
+                        "example": True
+                    },
+                    "message": {
+                        "type": "string",
+                        "example": "Service is running"
+                    },
+                    "data": {
+                        "type": "object",
+                        "properties": {
+                            "status": {
+                                "type": "string",
+                                "example": "healthy"
+                            },
+                            "service": {
+                                "type": "string",
+                                "example": "photoguard"
+                            },
+                            "api_version": {
+                                "type": "string",
+                                "example": "3.0.0"
+                            }
+                        }
+                    }
+                }
+            },
+            "ErrorResponse": {
+                "type": "object",
+                "properties": {
+                    "success": {
+                        "type": "boolean",
+                        "example": False
+                    },
+                    "message": {
+                        "type": "string",
+                        "description": "Error description",
+                        "example": "File type not allowed"
+                    }
+                }
+            }
+        }
+    }
+}

app/routes/upload.py

@@ -1,278 +1,151 @@
-from flask import Blueprint, request, jsonify, current_app, render_template, send_from_directory
+from flask import Blueprint, current_app, render_template, request, jsonify
 import os
 import uuid
-from werkzeug.utils import secure_filename
+from werkzeug.datastructures import FileStorage
 from werkzeug.exceptions import RequestEntityTooLarge
+from werkzeug.utils import secure_filename
 
 from app.services.quality_control import QualityControlService
 from app.utils.response_formatter import ResponseFormatter
+from app.api_spec import OPENAPI_SPEC
+
 
 upload_bp = Blueprint('upload', __name__)
 
-def allowed_file(filename):
-    """Check if file extension is allowed."""
-    return '.' in filename and \
-           filename.rsplit('.', 1)[1].lower() in current_app.config['ALLOWED_EXTENSIONS']
 
-@upload_bp.route('/upload', methods=['POST'])
-def upload_image():
-    """Upload and validate image endpoint."""
-    try:
-        # Check if file is in request
-        if 'image' not in request.files:
-            return ResponseFormatter.error("No image file provided", 400)
-        
-        file = request.files['image']
-        
-        # Check if file is selected
-        if file.filename == '':
-            return ResponseFormatter.error("No file selected", 400)
-        
-        # Check file type
-        if not allowed_file(file.filename):
-            return ResponseFormatter.error(
-                f"File type not allowed. Allowed types: {', '.join(current_app.config['ALLOWED_EXTENSIONS'])}",
-                400
-            )
-        
-        # Generate unique filename
-        filename = secure_filename(file.filename)
-        unique_filename = f"{uuid.uuid4()}_{filename}"
-        filepath = os.path.join(current_app.config['UPLOAD_FOLDER'], unique_filename)
-        
-        # Save file
-        file.save(filepath)
-        
-        # Initialize quality control service
-        qc_service = QualityControlService(current_app.config)
-        
-        # Validate image
-        validation_results = qc_service.validate_image(filepath)
-        
-        # Format response
-        return ResponseFormatter.success(
-            data=validation_results,
-            message="Image validation completed"
-        )
-        
-    except RequestEntityTooLarge:
-        return ResponseFormatter.error("File too large", 413)
-    except Exception as e:
-        return ResponseFormatter.error(f"Upload failed: {str(e)}", 500)
+class UploadError(Exception):
+    """Exception raised when an upload request is invalid."""
 
-@upload_bp.route('/validate-url', methods=['POST'])
-def validate_image_url():
-    """Validate image from URL endpoint."""
-    try:
-        data = request.get_json()
-        if not data or 'url' not in data:
-            return ResponseFormatter.error("No URL provided", 400)
-        
-        url = data['url']
-        
-        # Download image from URL (implement this as needed)
-        # For now, return not implemented
-        return ResponseFormatter.error("URL validation not yet implemented", 501)
-        
-    except Exception as e:
-        return ResponseFormatter.error(f"URL validation failed: {str(e)}", 500)
+    def __init__(self, message: str, status_code: int = 400) -> None:
+        super().__init__(message)
+        self.status_code = status_code
 
-@upload_bp.route('/summary', methods=['GET'])
-def get_validation_summary():
-    """Get validation statistics summary."""
-    try:
-        qc_service = QualityControlService(current_app.config)
-        summary = qc_service.get_validation_summary()
-        
-        return ResponseFormatter.success(
-            data=summary,
-            message="Validation summary retrieved"
-        )
-        
-    except Exception as e:
-        return ResponseFormatter.error(f"Failed to get summary: {str(e)}", 500)
 
-@upload_bp.route('/mobile', methods=['GET'])
-def mobile_interface():
-    """Serve mobile-friendly upload interface."""
-    return render_template('mobile_upload.html')
+def allowed_file(filename: str) -> bool:
+    """Return True when the provided filename has an allowed extension."""
+    if '.' not in filename:
+        return False
+    extension = filename.rsplit('.', 1)[1].lower()
+    return extension in current_app.config['ALLOWED_EXTENSIONS']
+
+
+def _extract_upload() -> FileStorage:
+    """Pull the uploaded file from the request or raise UploadError."""
+    if 'image' not in request.files:
+        raise UploadError("No image file provided", status_code=400)
+
+    file_storage = request.files['image']
+    if not isinstance(file_storage, FileStorage) or file_storage.filename == '':
+        raise UploadError("No file selected", status_code=400)
+
+    if not allowed_file(file_storage.filename):
+        allowed = ', '.join(sorted(current_app.config['ALLOWED_EXTENSIONS']))
+        raise UploadError(f"File type not allowed. Allowed types: {allowed}")
+
+    return file_storage
+
+
+def _store_upload(file_storage: FileStorage) -> str:
+    """Persist the uploaded file to the configured upload directory."""
+    upload_dir = current_app.config['UPLOAD_FOLDER']
+    os.makedirs(upload_dir, exist_ok=True)
+
+    filename = secure_filename(file_storage.filename)
+    unique_filename = f"{uuid.uuid4()}_{filename}"
+    filepath = os.path.join(upload_dir, unique_filename)
+    file_storage.save(filepath)
+    return filepath
+
 
 @upload_bp.route('/validate', methods=['POST'])
 def validate_image_api():
-    """
-    Comprehensive image validation API endpoint.
-    Returns detailed JSON results with all quality checks.
-    """
+    """Validate an uploaded image and return the consolidated scoring payload."""
     try:
-        # Check if file is in request
-        if 'image' not in request.files:
-            return ResponseFormatter.error("No image file provided", 400)
-        
-        file = request.files['image']
-        
-        # Check if file is selected
-        if file.filename == '':
-            return ResponseFormatter.error("No file selected", 400)
-        
-        # Check file type
-        if not allowed_file(file.filename):
-            return ResponseFormatter.error(
-                f"File type not allowed. Allowed types: {', '.join(current_app.config['ALLOWED_EXTENSIONS'])}",
-                400
-            )
-        
-        # Generate unique filename
-        filename = secure_filename(file.filename)
-        unique_filename = f"{uuid.uuid4()}_{filename}"
-        filepath = os.path.join(current_app.config['UPLOAD_FOLDER'], unique_filename)
-        
-        # Save file
-        file.save(filepath)
-        
-        # Initialize quality control service
+        file_storage = _extract_upload()
+        filepath = _store_upload(file_storage)
+
         qc_service = QualityControlService(current_app.config)
-        
-        # Validate image with new rules
         validation_results = qc_service.validate_image_with_new_rules(filepath)
-        
-        # Move image based on validation results
         qc_service.handle_validated_image(filepath, validation_results)
-        
-        # Format response in the new structure
+
         response_data = {
             "summary": {
-                "overall_status": validation_results['overall_status'],
-                "overall_score": validation_results['overall_score'],
-                "issues_found": validation_results['issues_found'],
-                "recommendations": validation_results['recommendations']
+                "overall_status": validation_results.get('overall_status'),
+                "overall_score": validation_results.get('overall_score'),
+                "issues_found": validation_results.get('issues_found'),
+                "recommendations": validation_results.get('recommendations', []),
             },
-            "checks": validation_results['checks']
+            "checks": validation_results.get('checks', {}),
         }
-        
+
         return ResponseFormatter.success(
             data=response_data,
             message="Image validation completed"
         )
-        
+
+    except UploadError as exc:
+        return ResponseFormatter.error(str(exc), exc.status_code)
     except RequestEntityTooLarge:
         return ResponseFormatter.error("File too large", 413)
-    except Exception as e:
-        return ResponseFormatter.error(f"Validation failed: {str(e)}", 500)
+    except Exception as exc:  # pragma: no cover - defensive safeguard
+        return ResponseFormatter.error(f"Validation failed: {exc}", 500)
+
 
 @upload_bp.route('/validation-rules', methods=['GET'])
 def get_validation_rules():
-    """Get current validation rules."""
+    """Expose the active validation rules for clients and documentation."""
     from config import Config
     config = Config()
-    
     return ResponseFormatter.success(
         data=config.VALIDATION_RULES,
         message="Current validation rules"
     )
 
-@upload_bp.route('/test-api', methods=['GET'])
-def test_api_endpoint():
-    """Test API endpoint with sample data."""
-    test_results = {
-        "api_version": "2.0",
-        "timestamp": "2025-09-25T11:00:00Z",
-        "validation_rules_applied": {
-            "blur": "variance_of_laplacian >= 100 (mobile-friendly)",
-            "brightness": "mean_pixel_intensity 50-220 (expanded range)",
-            "resolution": "min 800x600, >= 0.5MP (mobile-friendly)",
-            "exposure": "dynamic_range >= 100, clipping <= 2%",
-            "metadata": "6 required fields, >= 15% completeness",
-            "overall": "weighted scoring system, pass at >= 65% overall score"
-        },
-        "endpoints": {
-            "POST /api/validate": "Main validation endpoint",
-            "POST /api/upload": "Legacy upload endpoint", 
-            "GET /api/validation-rules": "Get current validation rules",
-            "GET /api/test-api": "This test endpoint",
-            "GET /api/health": "Health check",
-            "GET /api/summary": "Processing statistics"
-        },
-        "example_response_structure": {
-            "success": True,
-            "message": "Image validation completed",
-            "data": {
-                "summary": {
-                    "overall_status": "pass|fail",
-                    "overall_score": 80.0,
-                    "issues_found": 1,
-                    "recommendations": [
-                        "Use higher resolution camera setting",
-                        "Ensure camera metadata is enabled"
-                    ]
-                },
-                "checks": {
-                    "blur": {
-                        "status": "pass|fail",
-                        "score": 253.96,
-                        "threshold": 150,
-                        "reason": "Image sharpness is acceptable"
-                    },
-                    "brightness": {
-                        "status": "pass|fail",
-                        "mean_brightness": 128.94,
-                        "range": [90, 180],
-                        "reason": "Brightness is within the acceptable range"
-                    },
-                    "exposure": {
-                        "status": "pass|fail",
-                        "dynamic_range": 254,
-                        "threshold": 150,
-                        "reason": "Exposure and dynamic range are excellent"
-                    },
-                    "resolution": {
-                        "status": "pass|fail",
-                        "width": 1184,
-                        "height": 864,
-                        "megapixels": 1.02,
-                        "min_required": "1024x1024, ≥1 MP",
-                        "reason": "Resolution below minimum required size"
-                    },
-                    "metadata": {
-                        "status": "pass|fail",
-                        "completeness": 33.3,
-                        "required_min": 30,
-                        "missing_fields": ["timestamp", "camera_make_model", "orientation", "iso", "shutter_speed", "aperture"],
-                        "reason": "Sufficient metadata extracted"
-                    }
-                }
-            }
-        }
-    }
-    
-    return ResponseFormatter.success(
-        data=test_results,
-        message="API test information and example response structure"
-    )
+
+
+
 
 @upload_bp.route('/summary', methods=['GET'])
 def get_processing_summary():
-    """Get processing statistics and summary."""
+    """Return aggregate validation statistics for observability dashboards."""
     try:
         qc_service = QualityControlService(current_app.config)
         summary = qc_service.get_validation_summary()
-        
         return ResponseFormatter.success(
             data=summary,
             message="Processing summary retrieved"
         )
-        
-    except Exception as e:
-        return ResponseFormatter.error(f"Failed to get summary: {str(e)}", 500)
+    except Exception as exc:  # pragma: no cover - defensive safeguard
+        return ResponseFormatter.error(f"Failed to get summary: {exc}", 500)
+
 
 @upload_bp.route('/health', methods=['GET'])
 def health_check():
-    """Health check endpoint."""
+    """Simple health check endpoint for load balancers and monitors."""
     return ResponseFormatter.success(
         data={
-            "status": "healthy", 
-            "service": "civic-quality-control",
-            "api_version": "2.0",
+            "status": "healthy",
+            "service": "photoguard",
+            "api_version": "3.0.0",
             "validation_rules": "updated"
         },
-        message="Service is running with updated validation rules"
+        message="Service is running"
     )
+
+
+@upload_bp.route('/openapi.json', methods=['GET'])
+def get_openapi_spec():
+    """Return the OpenAPI 3.1 specification in JSON format."""
+    return jsonify(OPENAPI_SPEC)
+
+
+@upload_bp.route('/docs', methods=['GET'])
+def swagger_ui():
+    """Serve the Swagger UI documentation page."""
+    return render_template('swagger.html')
+
+
+@upload_bp.route('/redoc', methods=['GET'])
+def redoc_ui():
+    """Serve the ReDoc documentation page."""
+    return render_template('redoc.html')

app/services/quality_control.py

@@ -22,41 +22,20 @@ class QualityControlService:
             # Config class instance
             self.processed_folder = config.PROCESSED_FOLDER
             self.rejected_folder = config.REJECTED_FOLDER
-            self.yolo_model_path = config.YOLO_MODEL_PATH
             self.blur_threshold = config.BLUR_THRESHOLD
             self.min_brightness = config.MIN_BRIGHTNESS
             self.max_brightness = config.MAX_BRIGHTNESS
             self.min_resolution_width = config.MIN_RESOLUTION_WIDTH
             self.min_resolution_height = config.MIN_RESOLUTION_HEIGHT
-            self.city_boundaries = config.CITY_BOUNDARIES
         else:
             # Flask config object (dictionary-like)
             self.processed_folder = config.get('PROCESSED_FOLDER', 'storage/processed')
             self.rejected_folder = config.get('REJECTED_FOLDER', 'storage/rejected')
-            self.yolo_model_path = config.get('YOLO_MODEL_PATH', 'models/yolov8n.pt')
             self.blur_threshold = config.get('BLUR_THRESHOLD', 100.0)
             self.min_brightness = config.get('MIN_BRIGHTNESS', 30)
             self.max_brightness = config.get('MAX_BRIGHTNESS', 220)
             self.min_resolution_width = config.get('MIN_RESOLUTION_WIDTH', 800)
             self.min_resolution_height = config.get('MIN_RESOLUTION_HEIGHT', 600)
-            self.city_boundaries = config.get('CITY_BOUNDARIES', {
-                'min_lat': 40.4774,
-                'max_lat': 40.9176,
-                'min_lon': -74.2591,
-                'max_lon': -73.7004
-            })
-        
-        self.object_detector = None
-        self._initialize_object_detector()
-    
-    def _initialize_object_detector(self):
-        """Initialize object detector if model exists."""
-        try:
-            if os.path.exists(self.yolo_model_path):
-                from app.utils.object_detection import ObjectDetector
-                self.object_detector = ObjectDetector(self.yolo_model_path)
-        except Exception as e:
-            print(f"Warning: Object detector initialization failed: {e}")
     
     def validate_image(self, image_path: str) -> Dict:
         """
@@ -82,8 +61,7 @@ class QualityControlService:
                     "blur_detection": None,
                     "brightness_validation": None,
                     "resolution_check": None,
-                    "metadata_extraction": None,
-                    "object_detection": None
+                    "metadata_extraction": None
                 },
                 "metrics": {},
                 "recommendations": []
@@ -187,38 +165,9 @@ class QualityControlService:
                 metadata = MetadataExtractor.extract_metadata(image_path)
                 results["validations"]["metadata_extraction"] = metadata
                 
-                # Check GPS location if available
-                if metadata.get("gps_data"):
-                    location_validation = MetadataExtractor.validate_location(
-                        metadata["gps_data"], self.city_boundaries
-                    )
-                    if not location_validation["within_boundaries"]:
-                        results["warnings"].append({
-                            "type": "location",
-                            "message": location_validation["reason"]
-                        })
-                
             except Exception as e:
                 results["validations"]["metadata_extraction"] = {"error": str(e)}
-                results["warnings"].append(f"Metadata extraction failed: {str(e)}")            # 6. Object Detection (if available)
-            if self.object_detector:
-                try:
-                    detection_results = self.object_detector.detect_objects(image_path)
-                    results["validations"]["object_detection"] = detection_results
-
-                    if not detection_results["has_civic_content"]:
-                        results["warnings"].append({
-                            "type": "civic_content",
-                            "message": "No civic-related objects detected in image"
-                        })
-
-                except Exception as e:
-                    results["validations"]["object_detection"] = {"error": str(e)}
-                    results["warnings"].append(f"Object detection failed: {str(e)}")
-            else:
-                results["validations"]["object_detection"] = {
-                    "message": "Object detection not available - model not loaded"
-                }
+                results["warnings"].append(f"Metadata extraction failed: {str(e)}")
 
             # Calculate overall metrics
             results["metrics"] = self._calculate_metrics(results)

app/utils/blur_detection.py

@@ -1,6 +1,35 @@
 import cv2
 import numpy as np
-from typing import Tuple
+from typing import Optional, Tuple, Union
+
+
+def blur_score(image: Optional[Union[str, bytes, np.ndarray]]) -> float:
+    """Return Laplacian variance for backward-compatible API calls.
+
+    Accepts either a path to an image on disk or an in-memory numpy array.
+    When the input is ``None`` or invalid, ``0.0`` is returned so legacy
+    callers can treat the output as a failed blur computation.
+    """
+    if image is None:
+        return 0.0
+
+    try:
+        if isinstance(image, (str, bytes)):
+            frame = cv2.imread(image)
+        else:
+            frame = np.asarray(image)
+
+        if frame is None or frame.size == 0:
+            return 0.0
+
+        if frame.ndim == 3:
+            gray = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY)
+        else:
+            gray = frame
+
+        return float(cv2.Laplacian(gray, cv2.CV_64F).var())
+    except Exception:
+        return 0.0
 
 class BlurDetector:
     """Detects image blur using Laplacian variance method."""

app/utils/image_validation.py

@@ -1,77 +0,0 @@
-from .blur_detection import BlurDetector
-from .brightness_validation import BrightnessValidator
-from .resolution_check import ResolutionChecker
-from .metadata_extraction import MetadataExtractor
-from .object_detection import ObjectDetector
-
-class ImageValidator:
-    """Combined image validation class for legacy compatibility."""
-    
-    def __init__(self, blur_threshold=100, brightness_min=40, brightness_max=220, min_width=800, min_height=600):
-        self.blur_threshold = blur_threshold
-        self.brightness_min = brightness_min
-        self.brightness_max = brightness_max
-        self.min_width = min_width
-        self.min_height = min_height
-    
-    def validate_image(self, image_path: str) -> dict:
-        """
-        Validate image and return comprehensive results.
-        
-        Args:
-            image_path (str): Path to the image file
-            
-        Returns:
-            dict: Validation results
-        """
-        results = {
-            "blur": None,
-            "brightness": None,
-            "resolution": None,
-            "metadata": None,
-            "objects": None,
-            "overall_status": "UNKNOWN"
-        }
-        
-        try:
-            # Blur detection
-            blur_score, is_blurry = BlurDetector.calculate_blur_score(image_path, self.blur_threshold)
-            results["blur"] = BlurDetector.get_blur_details(blur_score, self.blur_threshold)
-            
-            # Brightness validation
-            results["brightness"] = BrightnessValidator.analyze_brightness(
-                image_path, self.brightness_min, self.brightness_max
-            )
-            
-            # Resolution check
-            results["resolution"] = ResolutionChecker.analyze_resolution(
-                image_path, self.min_width, self.min_height
-            )
-            
-            # Metadata extraction
-            results["metadata"] = MetadataExtractor.extract_metadata(image_path)
-            
-            # Object detection (if available)
-            try:
-                detector = ObjectDetector()
-                results["objects"] = detector.detect_objects(image_path)
-            except:
-                results["objects"] = {"error": "Object detection not available"}
-            
-            # Determine overall status
-            issues = []
-            if results["blur"]["is_blurry"]:
-                issues.append("blurry")
-            if results["brightness"]["has_brightness_issues"]:
-                issues.append("brightness")
-            if not results["resolution"]["meets_min_resolution"]:
-                issues.append("resolution")
-            
-            results["overall_status"] = "PASS" if not issues else "FAIL"
-            results["issues"] = issues
-            
-        except Exception as e:
-            results["error"] = str(e)
-            results["overall_status"] = "ERROR"
-        
-        return results

app/utils/metadata_extraction.py

@@ -255,33 +255,3 @@ class MetadataExtractor:
             "quality_level": quality_level,
             "meets_requirements": completeness_percentage >= 70
         }
-    
-    @staticmethod
-    def validate_location(gps_data: Dict, boundaries: Dict) -> Dict:
-        """Validate if GPS coordinates are within city boundaries."""
-        if not gps_data:
-            return {
-                "within_boundaries": False,
-                "reason": "No GPS data available"
-            }
-        
-        lat = gps_data.get("latitude")
-        lon = gps_data.get("longitude")
-        
-        if lat is None or lon is None:
-            return {
-                "within_boundaries": False,
-                "reason": "Invalid GPS coordinates"
-            }
-        
-        within_bounds = (
-            boundaries["min_lat"] <= lat <= boundaries["max_lat"] and
-            boundaries["min_lon"] <= lon <= boundaries["max_lon"]
-        )
-        
-        return {
-            "within_boundaries": within_bounds,
-            "latitude": lat,
-            "longitude": lon,
-            "reason": "Valid location" if within_bounds else "Outside city boundaries"
-        }

app/utils/object_detection.py

@@ -1,140 +0,0 @@
-from ultralytics import YOLO
-import cv2
-import numpy as np
-from typing import Dict, List, Tuple
-import os
-
-class ObjectDetector:
-    """Handles object detection using YOLO models."""
-    
-    def __init__(self, model_path: str = "models/yolov8n.pt"):
-        """Initialize YOLO model."""
-        self.model_path = model_path
-        self.model = None
-        self._load_model()
-    
-    def _load_model(self):
-        """Load YOLO model."""
-        try:
-            if os.path.exists(self.model_path):
-                self.model = YOLO(self.model_path)
-            else:
-                # Download model if not exists
-                self.model = YOLO("yolov8n.pt")
-                # Save to models directory
-                os.makedirs("models", exist_ok=True)
-                self.model.export(format="onnx")  # Optional: export to different format
-        except Exception as e:
-            raise Exception(f"Failed to load YOLO model: {str(e)}")
-    
-    def detect_objects(self, image_path: str, confidence_threshold: float = 0.5) -> Dict:
-        """
-        Detect objects in image using YOLO.
-        
-        Args:
-            image_path: Path to the image file
-            confidence_threshold: Minimum confidence for detections
-            
-        Returns:
-            Dictionary with detection results
-        """
-        try:
-            if self.model is None:
-                raise Exception("YOLO model not loaded")
-            
-            # Run inference
-            results = self.model(image_path, conf=confidence_threshold)
-            
-            # Process results
-            detections = []
-            civic_objects = []
-            
-            for result in results:
-                boxes = result.boxes
-                if boxes is not None:
-                    for box in boxes:
-                        # Get detection details
-                        confidence = float(box.conf[0])
-                        class_id = int(box.cls[0])
-                        class_name = self.model.names[class_id]
-                        bbox = box.xyxy[0].tolist()  # [x1, y1, x2, y2]
-                        
-                        detection = {
-                            "class_name": class_name,
-                            "confidence": round(confidence, 3),
-                            "bbox": [round(coord, 2) for coord in bbox],
-                            "area": (bbox[2] - bbox[0]) * (bbox[3] - bbox[1])
-                        }
-                        detections.append(detection)
-                        
-                        # Check for civic-related objects
-                        if self._is_civic_object(class_name):
-                            civic_objects.append(detection)
-            
-            return {
-                "total_detections": len(detections),
-                "all_detections": detections,
-                "civic_objects": civic_objects,
-                "civic_object_count": len(civic_objects),
-                "has_civic_content": len(civic_objects) > 0,
-                "summary": self._generate_detection_summary(detections)
-            }
-            
-        except Exception as e:
-            return {
-                "error": f"Object detection failed: {str(e)}",
-                "total_detections": 0,
-                "all_detections": [],
-                "civic_objects": [],
-                "civic_object_count": 0,
-                "has_civic_content": False
-            }
-    
-    def _is_civic_object(self, class_name: str) -> bool:
-        """Check if detected object is civic-related."""
-        civic_classes = [
-            "car", "truck", "bus", "motorcycle", "bicycle",
-            "traffic light", "stop sign", "bench", "fire hydrant",
-            "street sign", "pothole", "trash can", "dumpster"
-        ]
-        return class_name.lower() in [c.lower() for c in civic_classes]
-    
-    def _generate_detection_summary(self, detections: List[Dict]) -> Dict:
-        """Generate summary of detections."""
-        if not detections:
-            return {"message": "No objects detected"}
-        
-        # Count objects by class
-        class_counts = {}
-        for detection in detections:
-            class_name = detection["class_name"]
-            class_counts[class_name] = class_counts.get(class_name, 0) + 1
-        
-        # Find most confident detection
-        most_confident = max(detections, key=lambda x: x["confidence"])
-        
-        return {
-            "unique_classes": len(class_counts),
-            "class_counts": class_counts,
-            "most_confident_detection": {
-                "class": most_confident["class_name"],
-                "confidence": most_confident["confidence"]
-            },
-            "avg_confidence": round(
-                sum(d["confidence"] for d in detections) / len(detections), 3
-            )
-        }
-
-    def detect_specific_civic_issues(self, image_path: str) -> Dict:
-        """
-        Detect specific civic issues (future enhancement).
-        This would use a fine-tuned model for pothole, overflowing bins, etc.
-        """
-        # Placeholder for future implementation
-        return {
-            "potholes": [],
-            "overflowing_bins": [],
-            "broken_streetlights": [],
-            "graffiti": [],
-            "message": "Specific civic issue detection not yet implemented"
-        }

config.py

@@ -144,14 +144,6 @@ class Config:
         }
     }
     
-    # ===================================================================
-    # MACHINE LEARNING MODEL CONFIGURATION
-    # ===================================================================
-    
-    # Path to YOLOv8 object detection model
-    # Used for identifying civic-related objects (optional feature)
-    YOLO_MODEL_PATH = os.environ.get('YOLO_MODEL_PATH', 'models/yolov8n.pt')
-    
     # ===================================================================
     # FILE TYPE CONFIGURATION
     # ===================================================================
@@ -159,20 +151,6 @@ class Config:
     # Allowed image file extensions for upload
     # Supports common mobile photo formats including HEIC (iOS)
     ALLOWED_EXTENSIONS = set(os.environ.get('ALLOWED_EXTENSIONS', 'jpg,jpeg,png,bmp,tiff').split(','))
-    
-    # ===================================================================
-    # GEOGRAPHIC VALIDATION (Optional Feature)
-    # ===================================================================
-    
-    # Geographic boundaries for location validation
-    # Example coordinates for New York City area
-    # Customize these for your specific civic area
-    CITY_BOUNDARIES = {
-        'min_lat': 40.4774,  # Southern boundary (latitude)
-        'max_lat': 40.9176,  # Northern boundary (latitude)
-        'min_lon': -74.2591,  # Western boundary (longitude)
-        'max_lon': -73.7004  # Eastern boundary (longitude)
-    }
 
 
 # ===================================================================
@@ -189,11 +167,14 @@ class ProductionConfig(Config):
     """Production environment configuration with debug mode disabled."""
     DEBUG = False
     TESTING = False
-    
-    # Override with stricter settings if needed
-    # Example: Require HTTPS in production
-    # SESSION_COOKIE_SECURE = True
-    # SESSION_COOKIE_HTTPONLY = True
+
+
+class TestingConfig(Config):
+    """Testing configuration with deterministic behaviour."""
+    DEBUG = False
+    TESTING = True
+    # Use in-memory friendly limits to keep tests fast
+    MAX_CONTENT_LENGTH = int(os.environ.get('MAX_CONTENT_LENGTH', 8 * 1024 * 1024))
 
 
 # Configuration dictionary for easy access
@@ -201,5 +182,6 @@ class ProductionConfig(Config):
 config = {
     'development': DevelopmentConfig,
     'production': ProductionConfig,
+    'testing': TestingConfig,
     'default': DevelopmentConfig  # Default to development if not specified
 }

docker-compose.yml

@@ -1,41 +0,0 @@
-version: '3.8'
-
-services:
-  civic-quality:
-    build: .
-    container_name: civic-quality-app
-    ports:
-      - "8000:8000"
-    environment:
-      - SECRET_KEY=${SECRET_KEY:-change-this-in-production}
-      - FLASK_ENV=production
-      - BLUR_THRESHOLD=80.0
-      - MIN_BRIGHTNESS=25
-      - MAX_BRIGHTNESS=235
-    volumes:
-      - ./storage:/app/storage
-      - ./logs:/app/logs
-    restart: unless-stopped
-    healthcheck:
-      test: ["CMD", "curl", "-f", "http://localhost:8000/api/health"]
-      interval: 30s
-      timeout: 10s
-      retries: 3
-      start_period: 60s
-
-  nginx:
-    image: nginx:alpine
-    container_name: civic-quality-nginx
-    ports:
-      - "80:80"
-      - "443:443"
-    volumes:
-      - ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro
-      - ./nginx/ssl:/etc/nginx/ssl:ro
-    depends_on:
-      - civic-quality
-    restart: unless-stopped
-
-volumes:
-  storage:
-  logs:

docs/API.md

@@ -1,38 +0,0 @@
-# API Documentation
-
-## Endpoints
-
-### POST /check_quality
-
-Upload an image for quality control assessment.
-
-**Request:**
-- Content-Type: multipart/form-data
-- Body: image file
-
-**Response:**
-```json
-{
-  "status": "PASS|FAIL",
-  "checks": {
-    "blur": {
-      "value": 150.5,
-      "status": "OK"
-    },
-    "brightness": {
-      "value": 128.0,
-      "status": "OK"
-    },
-    "resolution": {
-      "value": "1920x1080",
-      "status": "OK"
-    }
-  },
-  "metadata": {
-    "format": "JPEG",
-    "size": [1920, 1080],
-    "mode": "RGB"
-  },
-  "objects": []
-}
-```

docs/API_v2.md

@@ -1,427 +0,0 @@
-# Civic Quality Control API Documentation
-
-**Version**: 2.0  
-**Base URL**: `http://localhost:5000/api` (development) | `http://your-domain.com/api` (production)  
-**Content-Type**: `application/json`
-
-## 📋 API Overview
-
-The Civic Quality Control API provides comprehensive image validation services optimized for mobile photography. It uses a weighted scoring system with partial credit to achieve realistic acceptance rates for civic documentation.
-
-### Key Features
-- **Weighted Validation**: 5-component analysis with intelligent scoring
-- **Mobile-Optimized**: Thresholds designed for smartphone cameras  
-- **High Performance**: <2 second processing time per image
-- **Comprehensive Feedback**: Detailed validation results and recommendations
-
----
-
-## 🔍 Endpoints
-
-### 1. Health Check
-
-**Endpoint**: `GET /api/health`  
-**Purpose**: System status and configuration verification
-
-**Response:**
-```json
-{
-  "success": true,
-  "data": {
-    "service": "civic-quality-control",
-    "status": "healthy",
-    "api_version": "2.0",
-    "validation_rules": "updated"
-  },
-  "message": "Service is running with updated validation rules",
-  "error": null
-}
-```
-
-**Example:**
-```bash
-curl http://localhost:5000/api/health
-```
-
----
-
-### 2. Image Validation (Primary Endpoint)
-
-**Endpoint**: `POST /api/validate`  
-**Purpose**: Comprehensive image quality validation with weighted scoring
-
-**Request:**
-```bash
-Content-Type: multipart/form-data
-Body: image=@your_image.jpg
-```
-
-**Response Structure:**
-```json
-{
-  "success": true,
-  "data": {
-    "summary": {
-      "overall_status": "PASS|FAIL",
-      "overall_score": 85.2,
-      "total_issues": 1,
-      "image_id": "20250925_143021_abc123_image.jpg"
-    },
-    "checks": {
-      "blur": {
-        "status": "PASS|FAIL",
-        "score": 95.0,
-        "weight": 25,
-        "message": "Image sharpness is excellent",
-        "details": {
-          "variance": 245.6,
-          "threshold": 100,
-          "quality_level": "excellent"
-        }
-      },
-      "resolution": {
-        "status": "PASS|FAIL",
-        "score": 100.0,
-        "weight": 25,
-        "message": "Resolution exceeds requirements",
-        "details": {
-          "width": 1920,
-          "height": 1080,
-          "megapixels": 2.07,
-          "min_required": 0.5
-        }
-      },
-      "brightness": {
-        "status": "PASS|FAIL",
-        "score": 80.0,
-        "weight": 20,
-        "message": "Brightness is within acceptable range",
-        "details": {
-          "mean_intensity": 142.3,
-          "range": [50, 220],
-          "quality_percentage": 75
-        }
-      },
-      "exposure": {
-        "status": "PASS|FAIL",
-        "score": 90.0,
-        "weight": 15,
-        "message": "Exposure and dynamic range are good",
-        "details": {
-          "dynamic_range": 128,
-          "clipping_percentage": 0.5,
-          "max_clipping_allowed": 2
-        }
-      },
-      "metadata": {
-        "status": "PASS|FAIL",  
-        "score": 60.0,
-        "weight": 15,
-        "message": "Sufficient metadata extracted",
-        "details": {
-          "completeness": 45,
-          "required": 15,
-          "extracted_fields": ["timestamp", "camera_make_model", "iso"]
-        }
-      }
-    },
-    "recommendations": [
-      "Consider reducing brightness slightly for optimal quality",
-      "Image is suitable for civic documentation"
-    ]
-  },
-  "message": "Image validation completed successfully",
-  "error": null
-}
-```
-
-**Scoring System:**
-- **Overall Score**: Weighted average of all validation checks
-- **Pass Threshold**: 65% overall score required
-- **Component Weights**:
-  - Blur Detection: 25%
-  - Resolution Check: 25%
-  - Brightness Validation: 20%
-  - Exposure Analysis: 15%
-  - Metadata Extraction: 15%
-
-**Example:**
-```bash
-curl -X POST -F 'image=@test_photo.jpg' http://localhost:5000/api/validate
-```
-
----
-
-### 3. Processing Statistics
-
-**Endpoint**: `GET /api/summary`  
-**Purpose**: System performance metrics and acceptance rates
-
-**Response:**
-```json
-{
-  "success": true,
-  "data": {
-    "total_processed": 156,
-    "accepted": 61,
-    "rejected": 95,
-    "acceptance_rate": 39.1,
-    "processing_stats": {
-      "avg_processing_time": 1.8,
-      "last_24_hours": {
-        "processed": 23,
-        "accepted": 9,
-        "acceptance_rate": 39.1
-      }
-    },
-    "common_rejection_reasons": [
-      "blur: 45%",
-      "resolution: 23%", 
-      "brightness: 18%",
-      "exposure: 8%",
-      "metadata: 6%"
-    ]
-  },
-  "message": "Processing statistics retrieved",
-  "error": null
-}
-```
-
-**Example:**
-```bash
-curl http://localhost:5000/api/summary
-```
-
----
-
-### 4. Validation Rules
-
-**Endpoint**: `GET /api/validation-rules`  
-**Purpose**: Current validation thresholds and requirements
-
-**Response:**
-```json
-{
-  "success": true,
-  "data": {
-    "blur": {
-      "min_score": 100,
-      "metric": "variance_of_laplacian",
-      "levels": {
-        "poor": 0,
-        "acceptable": 100,
-        "excellent": 300
-      }
-    },
-    "brightness": {
-      "range": [50, 220],
-      "metric": "mean_pixel_intensity",
-      "quality_score_min": 60
-    },
-    "resolution": {
-      "min_width": 800,
-      "min_height": 600,
-      "min_megapixels": 0.5,
-      "recommended_megapixels": 2
-    },
-    "exposure": {
-      "min_score": 100,
-      "metric": "dynamic_range",
-      "acceptable_range": [80, 150],
-      "check_clipping": {
-        "max_percentage": 2
-      }
-    },
-    "metadata": {
-      "min_completeness_percentage": 15,
-      "required_fields": [
-        "timestamp",
-        "camera_make_model", 
-        "orientation",
-        "iso",
-        "shutter_speed",
-        "aperture"
-      ]
-    }
-  },
-  "message": "Current validation rules",
-  "error": null
-}
-```
-
-**Example:**
-```bash
-curl http://localhost:5000/api/validation-rules
-```
-
----
-
-### 5. API Information
-
-**Endpoint**: `GET /api/test-api`  
-**Purpose**: API capabilities and endpoint documentation
-
-**Response:**
-```json
-{
-  "success": true,
-  "data": {
-    "api_version": "2.0",
-    "endpoints": {
-      "GET /api/health": "Health check",
-      "POST /api/validate": "Main validation endpoint", 
-      "GET /api/summary": "Processing statistics",
-      "GET /api/validation-rules": "Get current validation rules",
-      "GET /api/test-api": "This test endpoint",
-      "POST /api/upload": "Legacy upload endpoint"
-    },
-    "features": [
-      "Mobile-optimized validation",
-      "Weighted scoring system",
-      "Partial credit evaluation",
-      "Real-time processing",
-      "Comprehensive feedback"
-    ]
-  },
-  "message": "API information retrieved",
-  "error": null
-}
-```
-
----
-
-### 6. Legacy Upload (Deprecated)
-
-**Endpoint**: `POST /api/upload`  
-**Purpose**: Legacy endpoint for backward compatibility  
-**Status**: ⚠️ **Deprecated** - Use `/api/validate` instead
-
----
-
-## 📊 Validation Components
-
-### Blur Detection (25% Weight)
-- **Method**: Laplacian variance analysis
-- **Threshold**: 100 (mobile-optimized)
-- **Levels**: Poor (0-99), Acceptable (100-299), Excellent (300+)
-
-### Resolution Check (25% Weight)  
-- **Minimum**: 800×600 pixels (0.5 megapixels)
-- **Recommended**: 2+ megapixels
-- **Mobile-Friendly**: Optimized for smartphone cameras
-
-### Brightness Validation (20% Weight)
-- **Range**: 50-220 pixel intensity
-- **Method**: Histogram analysis
-- **Quality Threshold**: 60% minimum
-
-### Exposure Analysis (15% Weight)
-- **Dynamic Range**: 80-150 acceptable
-- **Clipping Check**: Max 2% clipped pixels
-- **Method**: Pixel value distribution analysis
-
-### Metadata Extraction (15% Weight)
-- **Required Completeness**: 15% (mobile-friendly)
-- **Key Fields**: Timestamp, camera info, settings
-- **EXIF Analysis**: Automatic extraction and validation
-
----
-
-## 🚨 Error Handling
-
-### Standard Error Response
-```json
-{
-  "success": false,
-  "data": null,
-  "message": "Error description",
-  "error": {
-    "code": "ERROR_CODE",
-    "details": "Detailed error information"
-  }
-}
-```
-
-### Common Error Codes
-- `INVALID_IMAGE`: Image format not supported or corrupted
-- `FILE_TOO_LARGE`: Image exceeds size limit (32MB)
-- `PROCESSING_ERROR`: Internal validation error
-- `MISSING_IMAGE`: No image provided in request
-- `SERVER_ERROR`: Internal server error
-
----
-
-## 🔧 Usage Examples
-
-### JavaScript/Fetch
-```javascript
-const formData = new FormData();
-formData.append('image', imageFile);
-
-fetch('/api/validate', {
-  method: 'POST',
-  body: formData
-})
-.then(response => response.json())
-.then(data => {
-  console.log('Validation result:', data);
-  if (data.success && data.data.summary.overall_status === 'PASS') {
-    console.log('Image accepted with score:', data.data.summary.overall_score);
-  }
-});
-```
-
-### Python/Requests
-```python
-import requests
-
-with open('image.jpg', 'rb') as f:
-    files = {'image': f}
-    response = requests.post('http://localhost:5000/api/validate', files=files)
-    
-result = response.json()
-if result['success'] and result['data']['summary']['overall_status'] == 'PASS':
-    print(f"Image accepted with score: {result['data']['summary']['overall_score']}")
-```
-
-### cURL Examples
-```bash
-# Validate image
-curl -X POST -F 'image=@photo.jpg' http://localhost:5000/api/validate
-
-# Check system health
-curl http://localhost:5000/api/health
-
-# Get processing statistics  
-curl http://localhost:5000/api/summary
-
-# View validation rules
-curl http://localhost:5000/api/validation-rules
-```
-
----
-
-## 📈 Performance Characteristics
-
-- **Processing Time**: <2 seconds per image
-- **Concurrent Requests**: Supports multiple simultaneous validations
-- **Memory Usage**: Optimized for mobile image sizes
-- **Acceptance Rate**: 35-40% for quality mobile photos
-- **Supported Formats**: JPG, JPEG, PNG, HEIC, WebP
-- **Maximum File Size**: 32MB
-
----
-
-## 🔒 Security Considerations
-
-- **File Type Validation**: Only image formats accepted
-- **Size Limits**: 32MB maximum file size
-- **Input Sanitization**: All uploads validated and sanitized
-- **Temporary Storage**: Images automatically cleaned up
-- **No Data Persistence**: Original images not permanently stored
-
----
-
-**Documentation Version**: 2.0  
-**API Version**: 2.0  
-**Last Updated**: September 25, 2025

docs/DEPLOYMENT.md

@@ -1,606 +0,0 @@
-# Production Deployment Guide
-
-**Version**: 2.0  
-**Status**: ✅ **Production Ready**  
-**Last Updated**: September 25, 2025
-
-## 🎯 Overview
-
-This guide covers deploying the **Civic Quality Control API v2.0** - a production-ready mobile photo validation system with weighted scoring and optimized acceptance rates for civic documentation.
-
-## 🚀 Key Production Features
-
-### **Advanced Validation System**
-- ⚖️ **Weighted Scoring**: Intelligent partial credit system (65% pass threshold)
-- 📱 **Mobile-Optimized**: Realistic thresholds for smartphone photography
-- 🎯 **High Acceptance Rate**: 35-40% acceptance rate for quality mobile photos
-- ⚡ **Fast Processing**: <2 seconds per image validation
-- 📊 **Comprehensive API**: 6 endpoints with detailed feedback
-
-### **Validation Components** 
-- 🔍 **Blur Detection** (25% weight) - Laplacian variance ≥100
-- 📐 **Resolution Check** (25% weight) - Min 800×600px, 0.5MP
-- 💡 **Brightness Validation** (20% weight) - Range 50-220 intensity
-- 🌅 **Exposure Analysis** (15% weight) - Dynamic range + clipping check
-- 📋 **Metadata Extraction** (15% weight) - 15% EXIF completeness required
-
----
-
-## 🏗️ Quick Start
-
-### 1. Prerequisites Check
-
-```bash
-# Verify Python version
-python --version  # Required: 3.8+
-
-# Check system resources
-# RAM: 2GB+ recommended
-# Storage: 1GB+ for models and processing
-# CPU: 2+ cores recommended
-```
-
-### 2. Local Development Setup
-
-```bash
-# Clone and navigate to project
-cd civic_quality_app
-
-# Install dependencies
-pip install -r requirements.txt
-
-# Setup directories and download models
-python scripts/setup_directories.py
-python scripts/download_models.py
-
-# Start development server
-python app.py
-
-# Test the API
-curl http://localhost:5000/api/health
-```
-
-**Access Points:**
-- **API Base**: `http://localhost:5000/api/`
-- **Mobile Interface**: `http://localhost:5000/mobile_upload.html`
-- **Health Check**: `http://localhost:5000/api/health`
-
-### 3. Production Deployment Options
-
-#### **Option A: Docker (Recommended)**
-
-```bash
-# Build production image
-docker build -t civic-quality-app:v2.0 .
-
-# Run with production settings
-docker run -d \
-  --name civic-quality-prod \
-  -p 8000:8000 \
-  -e SECRET_KEY=your-production-secret-key-here \
-  -e FLASK_ENV=production \
-  -v $(pwd)/storage:/app/storage \
-  -v $(pwd)/logs:/app/logs \
-  --restart unless-stopped \
-  civic-quality-app:v2.0
-
-# Or use Docker Compose
-docker-compose up -d
-```
-
-#### **Option B: Manual Production**
-
-```bash
-# Install production server
-pip install gunicorn
-
-# Run with Gunicorn (4 workers)
-gunicorn --bind 0.0.0.0:8000 \
-  --workers 4 \
-  --timeout 120 \
-  --max-requests 1000 \
-  --max-requests-jitter 100 \
-  production:app
-
-# Or use provided script
-chmod +x start_production.sh
-./start_production.sh
-```
-
-#### **Option C: Cloud Deployment**
-
-**AWS/Azure/GCP:**
-```bash
-# Use production Docker image
-# Configure load balancer for port 8000
-# Set environment variables via cloud console
-# Enable auto-scaling based on CPU/memory
-```
-
----
-
-## ⚙️ Production Configuration
-
-### **Environment Variables**
-
-```bash
-# === Core Application ===
-SECRET_KEY=your-256-bit-production-secret-key
-FLASK_ENV=production
-DEBUG=False
-
-# === File Handling ===
-MAX_CONTENT_LENGTH=33554432  # 32MB max file size
-UPLOAD_FOLDER=storage/temp
-PROCESSED_FOLDER=storage/processed
-REJECTED_FOLDER=storage/rejected
-
-# === Validation Thresholds (Mobile-Optimized) ===
-BLUR_THRESHOLD=100              # Laplacian variance minimum
-MIN_BRIGHTNESS=50               # Minimum pixel intensity
-MAX_BRIGHTNESS=220              # Maximum pixel intensity  
-MIN_RESOLUTION_WIDTH=800        # Minimum width pixels
-MIN_RESOLUTION_HEIGHT=600       # Minimum height pixels
-MIN_MEGAPIXELS=0.5             # Minimum megapixels
-METADATA_COMPLETENESS=15        # Required EXIF completeness %
-
-# === Performance ===
-WORKERS=4                       # Gunicorn workers
-MAX_REQUESTS=1000              # Requests per worker
-TIMEOUT=120                    # Request timeout seconds
-
-# === Security ===
-ALLOWED_EXTENSIONS=jpg,jpeg,png,heic,webp
-SECURE_HEADERS=True
-```
-
-### **Production Configuration File**
-
-Create `production_config.py`:
-```python
-import os
-from config import VALIDATION_RULES
-
-class ProductionConfig:
-    SECRET_KEY = os.environ.get('SECRET_KEY') or 'fallback-key-change-in-production'
-    MAX_CONTENT_LENGTH = 32 * 1024 * 1024  # 32MB
-    
-    # Optimized validation rules
-    VALIDATION_RULES = VALIDATION_RULES
-    
-    # Performance settings
-    SEND_FILE_MAX_AGE_DEFAULT = 31536000  # 1 year cache
-    PROPAGATE_EXCEPTIONS = True
-    
-    # Security
-    SESSION_COOKIE_SECURE = True
-    SESSION_COOKIE_HTTPONLY = True
-    WTF_CSRF_ENABLED = True
-```
-
----
-
-## 🏗️ Production Architecture
-
-### **System Components**
-
-```
-┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
-│   Load Balancer │────│  Civic Quality  │────│   File Storage  │
-│   (nginx/ALB)   │    │      API        │    │   (persistent)  │
-└─────────────────┘    └─────────────────┘    └─────────────────┘
-                              │
-                    ┌─────────────────┐
-                    │   ML Models     │
-                    │   (YOLOv8)      │
-                    └─────────────────┘
-```
-
-### **Nginx Configuration** (Optional Reverse Proxy)
-
-```nginx
-server {
-    listen 80;
-    server_name your-domain.com;
-    
-    client_max_body_size 32M;
-    
-    location / {
-        proxy_pass http://127.0.0.1:8000;
-        proxy_set_header Host $host;
-        proxy_set_header X-Real-IP $remote_addr;
-        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-        proxy_connect_timeout 120s;
-        proxy_read_timeout 120s;
-    }
-    
-    # Static files (if serving directly)
-    location /static/ {
-        alias /app/static/;
-        expires 1y;
-        add_header Cache-Control "public, immutable";
-    }
-}
-```
-
----
-
-## 📊 Performance & Monitoring
-
-### **Key Metrics to Monitor**
-
-```bash
-# Application Health
-curl http://your-domain.com/api/health
-
-# Processing Statistics
-curl http://your-domain.com/api/summary
-
-# Response Time Monitoring
-curl -w "@curl-format.txt" -o /dev/null -s http://your-domain.com/api/health
-```
-
-### **Expected Performance**
-
-- **Processing Time**: 1-3 seconds per image
-- **Acceptance Rate**: 35-40% for mobile photos
-- **Throughput**: 100+ images/minute (4 workers)
-- **Memory Usage**: ~200MB per worker
-- **CPU Usage**: 50-80% during processing
-
-### **Monitoring Setup**
-
-```bash
-# Application logs
-tail -f logs/app.log
-
-# System monitoring
-htop
-df -h  # Check disk space
-```
-
----
-
-## 🧪 Production Testing
-
-### **Pre-Deployment Testing**
-
-```bash
-# 1. Run comprehensive API tests
-python api_test.py
-
-# 2. Test production server locally
-gunicorn --bind 127.0.0.1:8000 production:app &
-curl http://localhost:8000/api/health
-
-# 3. Load testing (optional)
-# Use tools like Apache Bench, wrk, or Artillery
-ab -n 100 -c 10 http://localhost:8000/api/health
-```
-
-### **Post-Deployment Validation**
-
-```bash
-# 1. Health check
-curl https://your-domain.com/api/health
-
-# 2. Upload test image
-curl -X POST -F 'image=@test_mobile_photo.jpg' \
-     https://your-domain.com/api/validate
-
-# 3. Check processing statistics
-curl https://your-domain.com/api/summary
-
-# 4. Validate acceptance rate
-# Should be 35-40% for realistic mobile photos
-```
-
----
-
-## 🔒 Security Considerations
-
-### **Production Security Checklist**
-
-- ✅ **Environment Variables**: All secrets in environment variables
-- ✅ **File Validation**: Strict image format checking
-- ✅ **Size Limits**: 32MB maximum file size
-- ✅ **Input Sanitization**: All uploads validated
-- ✅ **Temporary Cleanup**: Auto-cleanup of temp files
-- ✅ **HTTPS**: SSL/TLS encryption in production
-- ✅ **Rate Limiting**: Consider implementing API rate limits
-- ✅ **Access Logs**: Monitor for suspicious activity
-
-### **Firewall Configuration**
-
-```bash
-# Allow only necessary ports
-ufw allow 22     # SSH
-ufw allow 80     # HTTP
-ufw allow 443    # HTTPS
-ufw deny 5000    # Block development port
-ufw enable
-```
-
----
-
-## 🚨 Troubleshooting
-
-### **Common Issues & Solutions**
-
-#### **1. Low Acceptance Rate**
-```bash
-# Check current rates
-curl http://localhost:8000/api/summary
-
-# Solution: Validation rules already optimized for mobile photos
-# Current acceptance rate: 35-40%
-# If still too low, adjust thresholds in config.py
-```
-
-#### **2. Performance Issues**
-```bash
-# Check processing time
-time curl -X POST -F 'image=@test.jpg' http://localhost:8000/api/validate
-
-# Solutions:
-# - Increase worker count
-# - Add more CPU/memory
-# - Optimize image preprocessing
-```
-
-#### **3. Memory Issues**
-```bash
-# Monitor memory usage
-free -h
-ps aux | grep gunicorn
-
-# Solutions:
-# - Reduce max file size
-# - Implement image resizing
-# - Restart workers periodically
-```
-
-#### **4. File Storage Issues**
-```bash
-# Check disk space
-df -h
-
-# Clean up old files
-find storage/temp -type f -mtime +1 -delete
-find storage/rejected -type f -mtime +7 -delete
-```
-
----
-
-## 📈 Scaling & Optimization
-
-### **Horizontal Scaling**
-
-```bash
-# Multiple server instances
-docker run -d --name civic-quality-1 -p 8001:8000 civic-quality-app:v2.0
-docker run -d --name civic-quality-2 -p 8002:8000 civic-quality-app:v2.0
-
-# Load balancer configuration
-# Route traffic across multiple instances
-```
-
-### **Performance Optimization**
-
-```python
-# config.py optimizations
-VALIDATION_RULES = {
-    # Already optimized for mobile photography
-    # Higher thresholds = lower acceptance but better quality
-    # Lower thresholds = higher acceptance but more false positives
-}
-```
-
-### **Future Enhancements**
-
-- [ ] **Redis Caching**: Cache validation results
-- [ ] **Background Processing**: Async image processing
-- [ ] **CDN Integration**: Faster image delivery
-- [ ] **Auto-scaling**: Dynamic worker adjustment
-- [ ] **Monitoring Dashboard**: Real-time metrics
-- [ ] **A/B Testing**: Validation rule optimization
-
----
-
-## 📚 Additional Resources
-
-### **API Documentation**
-- **Comprehensive API Docs**: `docs/API_v2.md`
-- **Response Format Examples**: See API documentation
-- **Error Codes Reference**: Listed in API docs
-
-### **Configuration Files**
-- **Validation Rules**: `config.py`
-- **Docker Setup**: `docker-compose.yml`
-- **Production Server**: `production.py`
-
-### **Testing Resources**
-- **API Test Suite**: `api_test.py`
-- **Individual Tests**: `test_*.py` files
-- **Sample Images**: `tests/sample_images/`
-
----
-
-**Deployment Status**: ✅ **Production Ready**  
-**API Version**: 2.0  
-**Acceptance Rate**: 35-40% (Optimized)  
-**Processing Speed**: <2 seconds per image  
-**Mobile Optimized**: ✅ Fully Compatible
-
-```yaml
-# docker-compose.yml
-version: '3.8'
-services:
-  civic-quality:
-    build: .
-    ports:
-      - "8000:8000"
-    environment:
-      - SECRET_KEY=${SECRET_KEY}
-      - FLASK_ENV=production
-    volumes:
-      - ./storage:/app/storage
-      - ./logs:/app/logs
-    restart: unless-stopped
-    
-  nginx:
-    image: nginx:alpine
-    ports:
-      - "80:80"
-      - "443:443"
-    volumes:
-      - ./nginx.conf:/etc/nginx/nginx.conf
-      - ./ssl:/etc/nginx/ssl
-    depends_on:
-      - civic-quality
-    restart: unless-stopped
-```
-
-### Option 2: Cloud Deployment
-
-#### Azure Container Apps
-
-```bash
-# Create resource group
-az group create --name civic-quality-rg --location eastus
-
-# Create container app environment
-az containerapp env create \
-  --name civic-quality-env \
-  --resource-group civic-quality-rg \
-  --location eastus
-
-# Deploy container app
-az containerapp create \
-  --name civic-quality-app \
-  --resource-group civic-quality-rg \
-  --environment civic-quality-env \
-  --image civic-quality-app:latest \
-  --target-port 8000 \
-  --ingress external \
-  --env-vars SECRET_KEY=your-secret-key
-```
-
-#### AWS ECS Fargate
-
-```json
-{
-  "family": "civic-quality-task",
-  "networkMode": "awsvpc",
-  "requiresCompatibilities": ["FARGATE"],
-  "cpu": "512",
-  "memory": "1024",
-  "executionRoleArn": "arn:aws:iam::account:role/ecsTaskExecutionRole",
-  "containerDefinitions": [
-    {
-      "name": "civic-quality",
-      "image": "your-registry/civic-quality-app:latest",
-      "portMappings": [
-        {
-          "containerPort": 8000,
-          "protocol": "tcp"
-        }
-      ],
-      "environment": [
-        {
-          "name": "SECRET_KEY",
-          "value": "your-secret-key"
-        }
-      ],
-      "logConfiguration": {
-        "logDriver": "awslogs",
-        "options": {
-          "awslogs-group": "/ecs/civic-quality",
-          "awslogs-region": "us-east-1",
-          "awslogs-stream-prefix": "ecs"
-        }
-      }
-    }
-  ]
-}
-```
-
-## Production Considerations
-
-### Security
-
-1. **HTTPS**: Always use HTTPS in production
-2. **Secret Key**: Use a strong, random secret key
-3. **File Validation**: All uploads are validated for type and size
-4. **CORS**: Configure CORS appropriately for your domain
-
-### Performance
-
-1. **Gunicorn**: Production WSGI server with multiple workers
-2. **Model Caching**: YOLO model loaded once and cached
-3. **File Cleanup**: Temporary files automatically cleaned up
-4. **Optimized Processing**: Parallel processing for multiple validations
-
-### Monitoring
-
-1. **Health Check**: `/api/health` endpoint for load balancer
-2. **Metrics**: Processing time and validation statistics
-3. **Logging**: Structured logging for debugging
-4. **Storage Monitoring**: Track processed/rejected ratios
-
-### Scaling
-
-1. **Horizontal**: Multiple container instances
-2. **Load Balancer**: Distribute requests across instances
-3. **Storage**: Use cloud storage for uploaded files
-4. **Database**: Optional database for audit logs
-
-## API Endpoints
-
-- `GET /api/mobile` - Mobile upload interface
-- `POST /api/upload` - Image upload and analysis
-- `GET /api/health` - Health check
-- `GET /api/summary` - Processing statistics
-
-## Testing Production Deployment
-
-```bash
-# Test health endpoint
-curl http://localhost:8000/api/health
-
-# Test image upload (mobile interface)
-open http://localhost:8000/api/mobile
-
-# Test API directly
-curl -X POST \
-  -F "image=@test_image.jpg" \
-  http://localhost:8000/api/upload
-```
-
-## Troubleshooting
-
-### Common Issues
-
-1. **Model download fails**: Check internet connectivity
-2. **Large file uploads**: Increase `MAX_CONTENT_LENGTH`
-3. **Permission errors**: Check file permissions on storage directories
-4. **Memory issues**: Increase container memory allocation
-
-### Logs
-
-```bash
-# View container logs
-docker logs civic-quality
-
-# View application logs
-tail -f logs/app.log
-```
-
-## Support
-
-For issues and support:
-
-1. Check the logs for error details
-2. Verify configuration settings
-3. Test with sample images
-4. Review the troubleshooting section

docs/DEPLOYMENT_CHECKLIST.md

@@ -1,351 +0,0 @@
-# Production Deployment Checklist
-
-**Civic Quality Control API v2.0**  
-**Date**: September 25, 2025  
-**Status**: ✅ Production Ready
-
----
-
-## 🎯 Pre-Deployment Verification
-
-### **✅ System Requirements Met**
-- [x] Python 3.8+ installed
-- [x] 2GB+ RAM available  
-- [x] 1GB+ storage space
-- [x] 2+ CPU cores (recommended)
-- [x] Network connectivity for model downloads
-
-### **✅ Core Functionality Validated**
-- [x] **API Health**: All 6 endpoints functional
-- [x] **Validation Pipeline**: Weighted scoring system working
-- [x] **Mobile Optimization**: Realistic thresholds implemented  
-- [x] **Acceptance Rate**: 35-40% achieved (improved from 16.67%)
-- [x] **Response Format**: New structured JSON format implemented
-- [x] **Performance**: <2 second processing time per image
-
-### **✅ Configuration Optimized**
-- [x] **Validation Rules**: Mobile-friendly thresholds set
-  - Blur threshold: 100 (Laplacian variance)
-  - Brightness range: 50-220 (pixel intensity)
-  - Resolution minimum: 800×600 pixels (0.5MP)
-  - Metadata requirement: 15% completeness
-  - Exposure range: 80-150 dynamic range
-- [x] **Weighted Scoring**: Partial credit system (65% pass threshold)
-- [x] **File Handling**: 32MB max size, proper format validation
-
----
-
-## 🔧 Deployment Options
-
-### **Option 1: Docker Deployment (Recommended)**
-
-#### **Pre-deployment Steps:**
-```bash
-# 1. Verify Docker installation
-docker --version
-docker-compose --version
-
-# 2. Build production image
-docker build -t civic-quality-app:v2.0 .
-
-# 3. Test locally first
-docker run -p 8000:8000 civic-quality-app:v2.0
-curl http://localhost:8000/api/health
-```
-
-#### **Production Deployment:**
-```bash
-# Set production environment variables
-export SECRET_KEY="your-256-bit-production-secret-key"
-export FLASK_ENV="production"
-
-# Deploy with Docker Compose
-docker-compose up -d
-
-# Verify deployment
-docker-compose ps
-docker-compose logs civic-quality-app
-```
-
-#### **Post-deployment Validation:**
-```bash
-# Health check
-curl http://your-domain:8000/api/health
-
-# Test image validation
-curl -X POST -F 'image=@test_mobile_photo.jpg' \
-     http://your-domain:8000/api/validate
-
-# Check statistics
-curl http://your-domain:8000/api/summary
-```
-
----
-
-### **Option 2: Manual Production Server**
-
-#### **Server Setup:**
-```bash
-# 1. Install production dependencies
-pip install -r requirements.txt gunicorn
-
-# 2. Setup directories
-python scripts/setup_directories.py
-python scripts/download_models.py
-
-# 3. Configure environment
-export SECRET_KEY="your-production-secret-key"
-export FLASK_ENV="production"
-export MAX_CONTENT_LENGTH="33554432"
-```
-
-#### **Start Production Server:**
-```bash
-# Using Gunicorn (recommended)
-gunicorn --bind 0.0.0.0:8000 \
-  --workers 4 \
-  --timeout 120 \
-  --max-requests 1000 \
-  production:app
-
-# Or use provided script
-chmod +x start_production.sh
-./start_production.sh
-```
-
----
-
-## 📊 Post-Deployment Testing
-
-### **✅ Comprehensive API Testing**
-
-```bash
-# Run full test suite
-python api_test.py
-
-# Expected results:
-# - 5/5 tests passed
-# - All endpoints responding correctly
-# - Acceptance rate: 35-40%
-# - Processing time: <2 seconds
-```
-
-### **✅ Load Testing (Optional)**
-
-```bash
-# Simple load test
-ab -n 100 -c 10 http://your-domain:8000/api/health
-
-# Image validation load test
-for i in {1..10}; do
-  curl -X POST -F 'image=@test_image.jpg' \
-       http://your-domain:8000/api/validate &
-done
-wait
-```
-
-### **✅ Mobile Interface Testing**
-
-1. **Access mobile interface**: `http://your-domain:8000/mobile_upload.html`
-2. **Test camera capture**: Use device camera to take photo
-3. **Test file upload**: Upload existing photo from gallery
-4. **Verify validation**: Check response format and scoring
-5. **Test various scenarios**: Different lighting, angles, quality
-
----
-
-## 🔒 Security Hardening
-
-### **✅ Production Security Checklist**
-
-- [x] **Environment Variables**: All secrets externalized
-- [x] **HTTPS**: SSL/TLS certificate configured (recommended)
-- [x] **File Validation**: Strict image format checking implemented
-- [x] **Size Limits**: 32MB maximum enforced
-- [x] **Input Sanitization**: All uploads validated and sanitized
-- [x] **Temporary Cleanup**: Auto-cleanup mechanisms in place
-- [x] **Error Handling**: No sensitive information in error responses
-
-### **✅ Firewall Configuration**
-
-```bash
-# Recommended firewall rules
-ufw allow 22     # SSH access
-ufw allow 80     # HTTP
-ufw allow 443    # HTTPS  
-ufw allow 8000   # API port (or use nginx proxy)
-ufw deny 5000    # Block development port
-ufw enable
-```
-
----
-
-## 📈 Monitoring & Maintenance
-
-### **✅ Key Metrics to Track**
-
-1. **Application Health**
-   ```bash
-   curl http://your-domain:8000/api/health
-   # Should return: "status": "healthy"
-   ```
-
-2. **Processing Statistics**
-   ```bash
-   curl http://your-domain:8000/api/summary
-   # Monitor acceptance rate (target: 35-40%)
-   ```
-
-3. **Response Times**
-   ```bash
-   time curl -X POST -F 'image=@test.jpg' \
-        http://your-domain:8000/api/validate
-   # Target: <2 seconds
-   ```
-
-4. **System Resources**
-   ```bash
-   htop           # CPU and memory usage
-   df -h          # Disk space
-   du -sh storage/  # Storage usage
-   ```
-
-### **✅ Log Monitoring**
-
-```bash
-# Application logs
-tail -f logs/app.log
-
-# Docker logs (if using Docker)
-docker-compose logs -f civic-quality-app
-
-# System logs
-journalctl -u civic-quality-app -f
-```
-
-### **✅ Maintenance Tasks**
-
-#### **Daily:**
-- [ ] Check application health endpoint
-- [ ] Monitor acceptance rates
-- [ ] Review error logs
-
-#### **Weekly:**
-- [ ] Clean up old temporary files
-- [ ] Review processing statistics
-- [ ] Check disk space usage
-- [ ] Monitor performance metrics
-
-#### **Monthly:**
-- [ ] Review and optimize validation rules if needed
-- [ ] Update dependencies (test first)
-- [ ] Backup configuration and logs
-- [ ] Performance optimization review
-
----
-
-## 🚨 Troubleshooting Guide
-
-### **Common Issues & Quick Fixes**
-
-#### **1. API Not Responding**
-```bash
-# Check if service is running
-curl http://localhost:8000/api/health
-
-# Restart if needed
-docker-compose restart civic-quality-app
-# OR
-pkill -f gunicorn && ./start_production.sh
-```
-
-#### **2. Low Acceptance Rate**
-```bash
-# Check current rate
-curl http://localhost:8000/api/summary
-
-# Current optimization: 35-40% acceptance rate
-# Rules already optimized for mobile photography
-# No action needed unless specific requirements change
-```
-
-#### **3. Slow Processing**
-```bash
-# Check response time
-time curl -X POST -F 'image=@test.jpg' \
-     http://localhost:8000/api/validate
-
-# If >3 seconds:
-# - Check CPU usage (htop)
-# - Consider increasing workers
-# - Check available memory
-```
-
-#### **4. Storage Issues**
-```bash
-# Check disk space
-df -h
-
-# Clean old files
-find storage/temp -type f -mtime +1 -delete
-find storage/rejected -type f -mtime +7 -delete
-```
-
----
-
-## 📋 Success Criteria
-
-### **✅ Deployment Successful When:**
-
-- [x] **Health Check**: Returns "healthy" status
-- [x] **All Endpoints**: 6 API endpoints responding correctly
-- [x] **Validation Working**: Images processed with weighted scoring
-- [x] **Mobile Optimized**: Realistic acceptance rates (35-40%)
-- [x] **Performance**: <2 second processing time
-- [x] **Response Format**: New structured JSON format
-- [x] **Error Handling**: Graceful error responses
-- [x] **Security**: File validation and size limits enforced
-- [x] **Monitoring**: Logs and metrics accessible
-
-### **✅ Production Metrics Targets**
-
-| Metric | Target | Status |
-|--------|--------|--------|
-| Acceptance Rate | 35-40% | ✅ Achieved |
-| Processing Time | <2 seconds | ✅ Achieved |
-| API Response Time | <500ms | ✅ Achieved |
-| Uptime | >99.9% | ✅ Ready |
-| Error Rate | <1% | ✅ Ready |
-
----
-
-## 🎉 Deployment Complete!
-
-**Status**: ✅ **PRODUCTION READY**
-
-Your Civic Quality Control API v2.0 is now ready for production deployment with:
-
-- **Optimized Mobile Photography Validation**
-- **Weighted Scoring System with Partial Credit**  
-- **35-40% Acceptance Rate (Improved from 16.67%)**
-- **Comprehensive API with 6 Endpoints**
-- **Production-Grade Performance & Security**
-
-### **Next Steps:**
-1. Deploy using your chosen method (Docker recommended)
-2. Configure monitoring and alerting
-3. Set up backup procedures  
-4. Document any custom configurations
-5. Train users on the mobile interface
-
-### **Support & Documentation:**
-- **API Documentation**: `docs/API_v2.md`
-- **Deployment Guide**: `docs/DEPLOYMENT.md`
-- **Main README**: `README.md`
-- **Test Suite**: Run `python api_test.py`
-
----
-
-**Deployment Checklist Version**: 2.0  
-**Completed**: September 25, 2025  
-**Ready for Production**: ✅ YES

models/__init__.py

@@ -1 +0,0 @@
-# Models package

models/model_loader.py

@@ -1,33 +0,0 @@
-import torch
-from ultralytics import YOLO
-
-def load_yolo_model(model_path='models/yolov8n.pt'):
-    """
-    Load YOLOv8 model for object detection.
-    
-    Args:
-        model_path (str): Path to the YOLO model file
-        
-    Returns:
-        YOLO: Loaded YOLO model
-    """
-    try:
-        model = YOLO(model_path)
-        return model
-    except Exception as e:
-        raise RuntimeError(f"Failed to load YOLO model: {e}")
-
-# Global model instance
-yolo_model = None
-
-def get_yolo_model():
-    """
-    Get the global YOLO model instance, loading it if necessary.
-    
-    Returns:
-        YOLO: The YOLO model instance
-    """
-    global yolo_model
-    if yolo_model is None:
-        yolo_model = load_yolo_model()
-    return yolo_model

nginx/nginx.conf

@@ -1,89 +0,0 @@
-events {
-    worker_connections 1024;
-}
-
-http {
-    upstream civic-quality {
-        server civic-quality:8000;
-    }
-
-    # Rate limiting
-    limit_req_zone $binary_remote_addr zone=upload:10m rate=10r/m;
-    
-    # File upload size
-    client_max_body_size 32M;
-    
-    # Timeouts
-    proxy_connect_timeout 60s;
-    proxy_send_timeout 60s;
-    proxy_read_timeout 60s;
-
-    server {
-        listen 80;
-        server_name _;
-        
-        # Redirect to HTTPS (uncomment for production)
-        # return 301 https://$server_name$request_uri;
-        
-        # For development, serve directly over HTTP
-        location / {
-            proxy_pass http://civic-quality;
-            proxy_set_header Host $host;
-            proxy_set_header X-Real-IP $remote_addr;
-            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-            proxy_set_header X-Forwarded-Proto $scheme;
-        }
-        
-        # Rate limit upload endpoint
-        location /api/upload {
-            limit_req zone=upload burst=5 nodelay;
-            proxy_pass http://civic-quality;
-            proxy_set_header Host $host;
-            proxy_set_header X-Real-IP $remote_addr;
-            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-            proxy_set_header X-Forwarded-Proto $scheme;
-        }
-        
-        # Health check endpoint
-        location /api/health {
-            proxy_pass http://civic-quality;
-            access_log off;
-        }
-    }
-
-    # HTTPS server (uncomment and configure for production)
-    # server {
-    #     listen 443 ssl http2;
-    #     server_name your-domain.com;
-    #     
-    #     ssl_certificate /etc/nginx/ssl/cert.pem;
-    #     ssl_certificate_key /etc/nginx/ssl/key.pem;
-    #     
-    #     # SSL configuration
-    #     ssl_protocols TLSv1.2 TLSv1.3;
-    #     ssl_ciphers HIGH:!aNULL:!MD5;
-    #     ssl_prefer_server_ciphers on;
-    #     
-    #     # Security headers
-    #     add_header X-Frame-Options DENY;
-    #     add_header X-Content-Type-Options nosniff;
-    #     add_header X-XSS-Protection "1; mode=block";
-    #     
-    #     location / {
-    #         proxy_pass http://civic-quality;
-    #         proxy_set_header Host $host;
-    #         proxy_set_header X-Real-IP $remote_addr;
-    #         proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-    #         proxy_set_header X-Forwarded-Proto $scheme;
-    #     }
-    #     
-    #     location /api/upload {
-    #         limit_req zone=upload burst=5 nodelay;
-    #         proxy_pass http://civic-quality;
-    #         proxy_set_header Host $host;
-    #         proxy_set_header X-Real-IP $remote_addr;
-    #         proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-    #         proxy_set_header X-Forwarded-Proto $scheme;
-    #     }
-    # }
-}

production.py

@@ -1,153 +0,0 @@
-#!/usr/bin/env python3
-"""
-Civic Photo Quality Control API - Production WSGI Application
-==============================================================
-Production-ready entry point for deployment with Gunicorn or similar WSGI servers.
-
-Usage:
-    gunicorn --bind 0.0.0.0:8000 --workers 4 production:app
-
-Features:
-- Automatic directory structure setup
-- Production logging configuration
-- Model initialization
-- Environment validation
-
-Author: Civic Quality Control Team
-Version: 2.0
-"""
-
-import os
-import sys
-import logging
-from pathlib import Path
-
-# Add project root to Python path for proper module imports
-project_root = Path(__file__).parent
-sys.path.insert(0, str(project_root))
-
-from app import create_app
-from config import Config
-
-
-def setup_logging():
-    """
-    Configure production-grade logging.
-    
-    Logs are written to both console (stdout) and log file (logs/app.log).
-    Log format includes timestamp, logger name, level, and message.
-    """
-    logging.basicConfig(
-        level=logging.INFO,  # INFO level for production (change to DEBUG for troubleshooting)
-        format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
-        handlers=[
-            logging.StreamHandler(sys.stdout),  # Console output
-            # File output (only if logs directory exists)
-            logging.FileHandler('logs/app.log') if os.path.exists('logs') else logging.StreamHandler()
-        ]
-    )
-
-
-def ensure_directories():
-    """
-    Create all required directory structures if they don't exist.
-    
-    Directories created:
-    - storage/temp: Temporary upload storage
-    - storage/processed: Accepted/validated images
-    - storage/rejected: Rejected images for analysis
-    - models: Machine learning model storage
-    - logs: Application log files
-    """
-    directories = [
-        'storage/temp',
-        'storage/processed',
-        'storage/rejected',
-        'models',
-        'logs'
-    ]
-    
-    for directory in directories:
-        Path(directory).mkdir(parents=True, exist_ok=True)
-        logging.info(f"Ensured directory exists: {directory}")
-
-        
-def download_models():
-    """
-    Download YOLOv8 object detection model if not already present.
-    
-    The model is used for optional civic object detection feature.
-    Downloads from Ultralytics repository on first run.
-    """
-    model_path = Path('models/yolov8n.pt')
-    if not model_path.exists():
-        try:
-            from ultralytics import YOLO
-            logging.info("YOLO model not found. Downloading...")
-            model = YOLO('yolov8n.pt')  # Downloads YOLOv8n (nano) model
-            logging.info("YOLO model download completed successfully.")
-        except Exception as e:
-            logging.warning(f"Failed to download YOLO model: {e}")
-            logging.info("Object detection feature will be disabled.")
-
-
-def create_production_app():
-    """
-    Create and configure the production Flask application.
-    
-    Steps performed:
-    1. Setup logging configuration
-    2. Ensure directory structure exists
-    3. Download required models (if missing)
-    4. Create Flask app with production configuration
-    5. Validate critical configuration settings
-    
-    Returns:
-        Flask application instance configured for production
-    """
-    # Step 1: Configure logging
-    setup_logging()
-    logging.info("=" * 60)
-    logging.info("Civic Photo Quality Control API - Production Startup")
-    logging.info("=" * 60)
-    
-    # Step 2: Setup directories
-    ensure_directories()
-    download_models()
-    
-    # Set production environment
-    os.environ['FLASK_ENV'] = 'production'
-    
-    # Create Flask app with production config
-    app = create_app('production')
-    
-    # Configure for production
-    app.config.update({
-        'MAX_CONTENT_LENGTH': 32 * 1024 * 1024,  # 32MB for mobile photos
-        'UPLOAD_FOLDER': 'storage/temp',
-        'PROCESSED_FOLDER': 'storage/processed',
-        'REJECTED_FOLDER': 'storage/rejected',
-        'SECRET_KEY': os.environ.get('SECRET_KEY', 'production-secret-key-change-me'),
-        'BLUR_THRESHOLD': 80.0,  # More lenient for mobile
-        'MIN_BRIGHTNESS': 25,
-        'MAX_BRIGHTNESS': 235,
-        'MIN_RESOLUTION_WIDTH': 720,
-        'MIN_RESOLUTION_HEIGHT': 480,
-    })
-    
-    logging.info("Civic Quality Control App started in production mode")
-    logging.info(f"Upload folder: {app.config['UPLOAD_FOLDER']}")
-    logging.info(f"Max file size: {app.config['MAX_CONTENT_LENGTH']} bytes")
-    
-    return app
-
-# Create the app instance for WSGI servers (gunicorn, uwsgi, etc.)
-app = create_production_app()
-
-if __name__ == '__main__':
-    # Development server (not recommended for production)
-    app.run(
-        host='0.0.0.0',
-        port=int(os.environ.get('PORT', 8000)),
-        debug=False
-    )

requirements.txt

@@ -1,13 +1,16 @@
-Flask==2.3.3
-Flask-CORS==4.0.0
-opencv-python==4.8.1.78
-Pillow==10.0.1
-numpy==1.24.3
-ultralytics==8.0.196
-python-dotenv==1.0.0
-pytest==7.4.2
-requests==2.31.0
+# Core web framework
+Flask==3.0.3
+Flask-CORS==4.0.1
+gunicorn==23.0.0
+
+# Image processing
+opencv-python==4.10.0.84
+Pillow==10.4.0
+numpy==2.1.2
+
+# Metadata & configuration
 piexif==1.1.3
-geopy==2.4.0
-gunicorn==21.2.0
-PyYAML==6.0.1
+python-dotenv==1.0.1
+
+# Development & testing
+pytest==8.3.3

scripts/download_models.py

@@ -1,32 +0,0 @@
-#!/usr/bin/env python3
-"""
-Script to download YOLO models.
-"""
-
-import os
-import urllib.request
-from pathlib import Path
-
-def download_yolo_model():
-    """Download YOLOv8 nano model if not exists."""
-    model_dir = Path("models")
-    model_dir.mkdir(exist_ok=True)
-    
-    model_path = model_dir / "yolov8n.pt"
-    
-    if model_path.exists():
-        print(f"Model already exists at {model_path}")
-        return
-    
-    # YOLOv8n URL (example, replace with actual)
-    url = "https://github.com/ultralytics/assets/releases/download/v0.0.0/yolov8n.pt"
-    
-    print(f"Downloading YOLOv8n model to {model_path}...")
-    try:
-        urllib.request.urlretrieve(url, model_path)
-        print("Download complete.")
-    except Exception as e:
-        print(f"Failed to download model: {e}")
-
-if __name__ == "__main__":
-    download_yolo_model()

scripts/setup_directories.py

@@ -1,27 +0,0 @@
-#!/usr/bin/env python3
-"""
-Script to set up project directories.
-"""
-
-import os
-from pathlib import Path
-
-def setup_directories():
-    """Create all necessary directories."""
-    dirs = [
-        "storage/temp",
-        "storage/processed", 
-        "storage/rejected",
-        "tests/sample_images/blurry",
-        "tests/sample_images/dark",
-        "tests/sample_images/low_res",
-        "tests/sample_images/good",
-        "docs"
-    ]
-    
-    for dir_path in dirs:
-        Path(dir_path).mkdir(parents=True, exist_ok=True)
-        print(f"Created directory: {dir_path}")
-
-if __name__ == "__main__":
-    setup_directories()

start_production.bat

@@ -1,74 +0,0 @@
-@echo off
-REM Production startup script for Civic Quality Control App (Windows)
-REM This script sets up and starts the production environment
-
-echo 🚀 Starting Civic Quality Control - Production Setup
-echo =================================================
-
-REM Check if Docker is installed
-docker --version >nul 2>&1
-if %errorlevel% neq 0 (
-    echo ❌ Docker is not installed. Please install Docker Desktop first.
-    pause
-    exit /b 1
-)
-
-REM Check if Docker Compose is installed
-docker-compose --version >nul 2>&1
-if %errorlevel% neq 0 (
-    echo ❌ Docker Compose is not installed. Please update Docker Desktop.
-    pause
-    exit /b 1
-)
-
-REM Create necessary directories
-echo 📁 Creating necessary directories...
-if not exist storage\temp mkdir storage\temp
-if not exist storage\processed mkdir storage\processed
-if not exist storage\rejected mkdir storage\rejected
-if not exist logs mkdir logs
-if not exist nginx\ssl mkdir nginx\ssl
-
-REM Set environment variables if not already set
-if not defined SECRET_KEY (
-    echo 🔐 Generating secret key...
-    set SECRET_KEY=change-this-in-production-windows
-)
-
-REM Build and start the application
-echo 🏗️  Building and starting the application...
-docker-compose up --build -d
-
-REM Wait for the application to start
-echo ⏳ Waiting for application to start...
-timeout /t 30 /nobreak >nul
-
-REM Test the application
-echo 🧪 Testing the application...
-python test_production.py --quick
-
-REM Show status
-echo.
-echo 📊 Container Status:
-docker-compose ps
-
-echo.
-echo 🎉 Production deployment completed!
-echo =================================================
-echo 📱 Mobile Interface: http://localhost/api/mobile
-echo 🔍 Health Check: http://localhost/api/health
-echo 📊 API Documentation: http://localhost/api/summary
-echo.
-echo 📋 Management Commands:
-echo   Stop:    docker-compose down
-echo   Logs:    docker-compose logs -f
-echo   Restart: docker-compose restart
-echo   Test:    python test_production.py
-echo.
-echo ⚠️  For production use:
-echo   1. Configure HTTPS with SSL certificates
-echo   2. Set a secure SECRET_KEY environment variable
-echo   3. Configure domain-specific CORS settings
-echo   4. Set up monitoring and log aggregation
-
-pause

start_production.sh

@@ -1,65 +0,0 @@
-#!/bin/bash
-
-# Production startup script for Civic Quality Control App
-# This script sets up and starts the production environment
-
-set -e
-
-echo "🚀 Starting Civic Quality Control - Production Setup"
-echo "================================================="
-
-# Check if Docker is installed
-if ! command -v docker &> /dev/null; then
-    echo "❌ Docker is not installed. Please install Docker first."
-    exit 1
-fi
-
-# Check if Docker Compose is installed
-if ! command -v docker-compose &> /dev/null; then
-    echo "❌ Docker Compose is not installed. Please install Docker Compose first."
-    exit 1
-fi
-
-# Create necessary directories
-echo "📁 Creating necessary directories..."
-mkdir -p storage/temp storage/processed storage/rejected logs nginx/ssl
-
-# Set environment variables
-export SECRET_KEY=${SECRET_KEY:-$(openssl rand -hex 32)}
-echo "🔐 Secret key configured"
-
-# Build and start the application
-echo "🏗️  Building and starting the application..."
-docker-compose up --build -d
-
-# Wait for the application to start
-echo "⏳ Waiting for application to start..."
-sleep 30
-
-# Test the application
-echo "🧪 Testing the application..."
-python test_production.py --quick
-
-# Show status
-echo ""
-echo "📊 Container Status:"
-docker-compose ps
-
-echo ""
-echo "🎉 Production deployment completed!"
-echo "================================================="
-echo "📱 Mobile Interface: http://localhost/api/mobile"
-echo "🔍 Health Check: http://localhost/api/health"
-echo "📊 API Documentation: http://localhost/api/summary"
-echo ""
-echo "📋 Management Commands:"
-echo "  Stop:    docker-compose down"
-echo "  Logs:    docker-compose logs -f"
-echo "  Restart: docker-compose restart"
-echo "  Test:    python test_production.py"
-echo ""
-echo "⚠️  For production use:"
-echo "  1. Configure HTTPS with SSL certificates"
-echo "  2. Set a secure SECRET_KEY environment variable"
-echo "  3. Configure domain-specific CORS settings"
-echo "  4. Set up monitoring and log aggregation"

templates/index.html

@@ -0,0 +1,806 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>PhotoGuard - Image Quality Validation API</title>
+    <style>
+        * {
+            margin: 0;
+            padding: 0;
+            box-sizing: border-box;
+        }
+
+        :root {
+            --black: #000000;
+            --charcoal: #1a1a1a;
+            --dark-gray: #2d2d2d;
+            --medium-gray: #6b6b6b;
+            --light-gray: #a8a8a8;
+            --silver: #cccccc;
+            --off-white: #f5f5f5;
+            --white: #ffffff;
+            --success: #4a4a4a;
+            --error: #1a1a1a;
+        }
+
+        body {
+            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+            background: var(--off-white);
+            color: var(--charcoal);
+            line-height: 1.6;
+        }
+
+        /* Navigation */
+        nav {
+            background: var(--black);
+            border-bottom: 2px solid var(--dark-gray);
+            padding: 1rem 0;
+            position: sticky;
+            top: 0;
+            z-index: 100;
+            box-shadow: 0 2px 8px rgba(0,0,0,0.3);
+        }
+
+        .nav-container {
+            max-width: 1200px;
+            margin: 0 auto;
+            padding: 0 2rem;
+            display: flex;
+            justify-content: space-between;
+            align-items: center;
+        }
+
+        .logo {
+            font-size: 1.5rem;
+            font-weight: 700;
+            color: var(--white);
+            letter-spacing: 0.5px;
+        }
+
+        .nav-links {
+            display: flex;
+            gap: 2rem;
+            list-style: none;
+        }
+
+        .nav-links a {
+            text-decoration: none;
+            color: var(--light-gray);
+            font-weight: 500;
+            transition: color 0.2s;
+            text-transform: uppercase;
+            font-size: 0.9rem;
+            letter-spacing: 1px;
+        }
+
+        .nav-links a:hover {
+            color: var(--white);
+        }
+
+        /* Hero Section */
+        .hero {
+            background: linear-gradient(135deg, var(--charcoal) 0%, var(--black) 100%);
+            color: var(--white);
+            padding: 4rem 2rem;
+            text-align: center;
+            border-bottom: 4px solid var(--dark-gray);
+        }
+
+        .hero h1 {
+            font-size: 3rem;
+            margin-bottom: 1rem;
+            font-weight: 800;
+        }
+
+        .hero p {
+            font-size: 1.25rem;
+            color: var(--light-gray);
+            max-width: 700px;
+            margin: 0 auto 2rem;
+            line-height: 1.8;
+        }
+
+        /* Container */
+        .container {
+            max-width: 1200px;
+            margin: 0 auto;
+            padding: 3rem 2rem;
+        }
+
+        section {
+            margin-bottom: 4rem;
+        }
+
+        section h2 {
+            font-size: 2rem;
+            margin-bottom: 1rem;
+            color: var(--black);
+            font-weight: 700;
+            letter-spacing: -0.5px;
+        }
+
+        /* Upload Section */
+        .upload-area {
+            background: var(--white);
+            border: 3px dashed var(--silver);
+            border-radius: 4px;
+            padding: 3rem;
+            text-align: center;
+            cursor: pointer;
+            transition: all 0.3s;
+            margin-bottom: 2rem;
+        }
+
+        .upload-area:hover {
+            border-color: var(--medium-gray);
+            background: var(--off-white);
+        }
+
+        .upload-area.dragover {
+            border-color: var(--charcoal);
+            background: var(--off-white);
+        }
+
+        .upload-icon {
+            font-size: 4rem;
+            margin-bottom: 1rem;
+        }
+
+        .file-input {
+            display: none;
+        }
+
+        .btn {
+            padding: 0.75rem 2rem;
+            border-radius: 2px;
+            border: none;
+            font-weight: 600;
+            cursor: pointer;
+            transition: all 0.2s;
+            font-size: 1rem;
+            text-transform: uppercase;
+            letter-spacing: 1px;
+        }
+
+        .btn-primary {
+            background: var(--black);
+            color: var(--white);
+        }
+
+        .btn-primary:hover {
+            background: var(--charcoal);
+        }
+
+        .btn-secondary {
+            background: var(--white);
+            color: var(--black);
+            border: 2px solid var(--black);
+        }
+
+        .btn-secondary:hover {
+            background: var(--black);
+            color: var(--white);
+        }
+
+        /* Results */
+        .results {
+            display: none;
+            background: var(--white);
+            border-radius: 4px;
+            padding: 2rem;
+            box-shadow: 0 2px 8px rgba(0,0,0,0.15);
+            border: 1px solid var(--silver);
+        }
+
+        .results.show {
+            display: block;
+        }
+
+        .status-badge {
+            display: inline-block;
+            padding: 0.5rem 1rem;
+            border-radius: 2px;
+            font-weight: 600;
+            margin-bottom: 1rem;
+            text-transform: uppercase;
+            letter-spacing: 1px;
+        }
+
+        .status-badge.pass {
+            background: var(--dark-gray);
+            color: var(--white);
+            border: 2px solid var(--black);
+        }
+
+        .status-badge.fail {
+            background: var(--white);
+            color: var(--black);
+            border: 2px solid var(--black);
+        }
+
+        .validation-grid {
+            display: grid;
+            grid-template-columns: repeat(auto-fit, minmax(250px, 1fr));
+            gap: 1rem;
+            margin: 2rem 0;
+        }
+
+        .validation-card {
+            background: var(--off-white);
+            border-radius: 2px;
+            padding: 1.5rem;
+            border-left: 4px solid var(--silver);
+            border: 1px solid var(--silver);
+        }
+
+        .validation-card.pass {
+            border-left-color: var(--black);
+            background: var(--white);
+        }
+
+        .validation-card.fail {
+            border-left-color: var(--medium-gray);
+        }
+
+        .validation-card h4 {
+            margin-bottom: 0.5rem;
+            display: flex;
+            align-items: center;
+            gap: 0.5rem;
+            color: var(--charcoal);
+            font-weight: 600;
+        }
+
+        .validation-card .score {
+            font-size: 1.5rem;
+            font-weight: 700;
+            color: var(--black);
+            margin: 0.5rem 0;
+        }
+
+        /* How It Works */
+        .steps {
+            display: grid;
+            grid-template-columns: repeat(auto-fit, minmax(250px, 1fr));
+            gap: 2rem;
+            margin-top: 2rem;
+        }
+
+        .step {
+            text-align: center;
+            padding: 2rem;
+            background: var(--white);
+            border-radius: 2px;
+            border: 1px solid var(--silver);
+        }
+
+        .step-number {
+            width: 60px;
+            height: 60px;
+            background: var(--black);
+            color: var(--white);
+            border-radius: 50%;
+            display: flex;
+            align-items: center;
+            justify-content: center;
+            font-size: 1.5rem;
+            font-weight: 700;
+            margin: 0 auto 1rem;
+        }
+
+        .step h3 {
+            margin-bottom: 0.5rem;
+            color: var(--charcoal);
+            font-weight: 600;
+        }
+
+        .step p {
+            color: var(--medium-gray);
+        }
+
+        /* API Documentation */
+        .api-card {
+            background: var(--white);
+            border-radius: 2px;
+            padding: 2rem;
+            margin-bottom: 1.5rem;
+            box-shadow: 0 2px 4px rgba(0,0,0,0.1);
+            border: 1px solid var(--silver);
+        }
+
+        .api-card h3 {
+            margin-bottom: 1rem;
+            color: var(--black);
+            font-weight: 700;
+        }
+
+        .api-buttons {
+            display: flex;
+            gap: 1rem;
+            margin-top: 2rem;
+        }
+
+        .api-btn {
+            flex: 1;
+            padding: 2rem;
+            background: var(--white);
+            border: 2px solid var(--black);
+            border-radius: 2px;
+            text-align: center;
+            cursor: pointer;
+            transition: all 0.3s;
+            text-decoration: none;
+            color: var(--charcoal);
+            display: block;
+        }
+
+        .api-btn:hover {
+            background: var(--black);
+            color: var(--white);
+            transform: translateY(-2px);
+        }
+
+        .api-btn:hover h4 {
+            color: var(--white);
+        }
+
+        .api-btn:hover p {
+            color: var(--light-gray);
+        }
+
+        .api-btn h4 {
+            font-size: 1.25rem;
+            margin-bottom: 0.5rem;
+            color: var(--black);
+            font-weight: 700;
+        }
+
+        .api-btn p {
+            color: var(--medium-gray);
+            font-size: 0.9rem;
+        }
+
+        .endpoint {
+            background: var(--off-white);
+            border-left: 4px solid var(--black);
+            padding: 1rem;
+            margin: 1rem 0;
+            border-radius: 2px;
+            border: 1px solid var(--silver);
+        }
+
+        .endpoint-method {
+            display: inline-block;
+            background: var(--black);
+            color: var(--white);
+            padding: 0.25rem 0.75rem;
+            border-radius: 2px;
+            font-weight: 600;
+            font-size: 0.8rem;
+            margin-right: 0.5rem;
+            text-transform: uppercase;
+            letter-spacing: 1px;
+        }
+
+        .endpoint-method.get {
+            background: var(--dark-gray);
+        }
+
+        .endpoint-path {
+            font-family: 'Courier New', monospace;
+            color: var(--charcoal);
+            font-weight: 600;
+        }
+
+        .endpoint-desc {
+            margin-top: 0.5rem;
+            color: var(--medium-gray);
+            font-size: 0.9rem;
+        }
+
+        .features-grid {
+            display: grid;
+            grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
+            gap: 1.5rem;
+            margin-top: 2rem;
+        }
+
+        .feature-item {
+            display: flex;
+            align-items: flex-start;
+            gap: 0.75rem;
+        }
+
+        .feature-icon {
+            font-size: 1.5rem;
+            flex-shrink: 0;
+        }
+
+        .loading {
+            display: none;
+            text-align: center;
+            padding: 2rem;
+        }
+
+        .loading.show {
+            display: block;
+        }
+
+        .spinner {
+            border: 4px solid var(--silver);
+            border-top: 4px solid var(--black);
+            border-radius: 50%;
+            width: 50px;
+            height: 50px;
+            animation: spin 1s linear infinite;
+            margin: 0 auto;
+        }
+
+        @keyframes spin {
+            0% { transform: rotate(0deg); }
+            100% { transform: rotate(360deg); }
+        }
+
+        /* Responsive */
+        @media (max-width: 768px) {
+            .hero h1 {
+                font-size: 2rem;
+            }
+            
+            .nav-links {
+                gap: 1rem;
+            }
+            
+            .api-buttons {
+                flex-direction: column;
+            }
+        }
+    </style>
+</head>
+<body>
+    <!-- Navigation -->
+    <nav>
+        <div class="nav-container">
+            <div class="logo">�️ PhotoGuard</div>
+            <ul class="nav-links">
+                <li><a href="#home">Home</a></li>
+                <li><a href="#how-it-works">How It Works</a></li>
+                <li><a href="#api-docs">API Docs</a></li>
+            </ul>
+        </div>
+    </nav>
+
+    <!-- Hero Section -->
+    <div class="hero" id="home">
+        <h1>PhotoGuard</h1>
+        <p>Professional image quality validation API with automated blur detection, brightness analysis, resolution checking, exposure verification, and metadata extraction</p>
+    </div>
+
+    <!-- Main Container -->
+    <div class="container">
+        <!-- Upload Section -->
+        <section>
+            <h2>Upload Image for Validation</h2>
+            <div class="upload-area" id="uploadArea">
+                <div class="upload-icon">📁</div>
+                <h3>Drop your image here or click to browse</h3>
+                <p style="color: var(--medium-gray); margin-top: 0.5rem;">Supports JPG, PNG, HEIC (Max 16MB)</p>
+                <input type="file" id="fileInput" class="file-input" accept="image/*">
+            </div>
+
+            <!-- Loading State -->
+            <div class="loading" id="loading">
+                <div class="spinner"></div>
+                <p style="margin-top: 1rem; color: var(--medium-gray);">Analyzing image quality...</p>
+            </div>
+
+            <!-- Results -->
+            <div class="results" id="results">
+                <div style="display: flex; justify-content: space-between; align-items: center; margin-bottom: 1rem;">
+                    <h3>Validation Results</h3>
+                    <button class="btn btn-secondary" onclick="resetUpload()">Upload Another Image</button>
+                </div>
+                
+                <div id="statusBadge"></div>
+                <div id="validationGrid" class="validation-grid"></div>
+                <div id="recommendations"></div>
+            </div>
+        </section>
+
+        <!-- How It Works -->
+        <section id="how-it-works">
+            <h2>How It Works</h2>
+            <div class="steps">
+                <div class="step">
+                    <div class="step-number">1</div>
+                    <h3>Upload Image</h3>
+                    <p>Drag & drop or browse to select an image file from your device</p>
+                </div>
+                <div class="step">
+                    <div class="step-number">2</div>
+                    <h3>Quality Analysis</h3>
+                    <p>Automated 5-layer validation checks every aspect of image quality</p>
+                </div>
+                <div class="step">
+                    <div class="step-number">3</div>
+                    <h3>Receive Report</h3>
+                    <p>Get instant validation results with scores and improvement recommendations</p>
+                </div>
+            </div>
+        </section>
+
+        <!-- API Documentation -->
+        <section id="api-docs">
+            <h2>API Documentation</h2>
+            
+            <div class="api-card">
+                <h3>Interactive API Documentation</h3>
+                <p>Test and explore PhotoGuard API endpoints directly in your browser with interactive documentation tools</p>
+            </div>
+
+            <div class="api-buttons">
+                <div class="api-btn" onclick="window.open('/api/docs', '_blank')">
+                    <h4>📘 Swagger UI</h4>
+                    <p>Interactive testing interface with live API execution and request builder</p>
+                </div>
+                <div class="api-btn" onclick="window.open('/api/redoc', '_blank')">
+                    <h4>📖 ReDoc</h4>
+                    <p>Comprehensive API reference with detailed schemas and examples</p>
+                </div>
+            </div>
+
+            <div class="api-card" style="margin-top: 2rem;">
+                <h3>Available Endpoints</h3>
+                
+                <div class="endpoint">
+                    <span class="endpoint-method">POST</span>
+                    <span class="endpoint-path">/api/validate</span>
+                    <div class="endpoint-desc">
+                        Upload and validate image quality across all parameters (blur, brightness, resolution, exposure, metadata)
+                        <br><strong>Request:</strong> multipart/form-data with image file
+                        <br><strong>Response:</strong> Complete validation report with scores and recommendations
+                    </div>
+                </div>
+
+                <div class="endpoint">
+                    <span class="endpoint-method get">GET</span>
+                    <span class="endpoint-path">/api/validation-rules</span>
+                    <div class="endpoint-desc">
+                        Retrieve current validation thresholds and quality requirements
+                        <br><strong>Response:</strong> Configuration rules with threshold values
+                    </div>
+                </div>
+
+                <div class="endpoint">
+                    <span class="endpoint-method get">GET</span>
+                    <span class="endpoint-path">/api/summary</span>
+                    <div class="endpoint-desc">
+                        View processing statistics and quality metrics
+                        <br><strong>Response:</strong> Aggregated data on processed images and acceptance rates
+                    </div>
+                </div>
+
+                <div class="endpoint">
+                    <span class="endpoint-method get">GET</span>
+                    <span class="endpoint-path">/api/health</span>
+                    <div class="endpoint-desc">
+                        Check API service health and availability status
+                        <br><strong>Response:</strong> Service status, API version, and system information
+                    </div>
+                </div>
+            </div>
+
+            <div class="api-card">
+                <h3>Core Validation Features</h3>
+                <div class="features-grid">
+                    <div class="feature-item">
+                        <span class="feature-icon">▪</span>
+                        <div>
+                            <strong>Blur Detection</strong><br>
+                            <span style="color: var(--medium-gray); font-size: 0.9rem;">Advanced Laplacian variance analysis measures image sharpness</span>
+                        </div>
+                    </div>
+                    <div class="feature-item">
+                        <span class="feature-icon">▪</span>
+                        <div>
+                            <strong>Brightness Validation</strong><br>
+                            <span style="color: var(--medium-gray); font-size: 0.9rem;">Pixel intensity analysis with optimal 50-220 luminance range</span>
+                        </div>
+                    </div>
+                    <div class="feature-item">
+                        <span class="feature-icon">▪</span>
+                        <div>
+                            <strong>Resolution Verification</strong><br>
+                            <span style="color: var(--medium-gray); font-size: 0.9rem;">Validates minimum 800×600 pixels and 0.5MP requirement</span>
+                        </div>
+                    </div>
+                    <div class="feature-item">
+                        <span class="feature-icon">▪</span>
+                        <div>
+                            <strong>Exposure Analysis</strong><br>
+                            <span style="color: var(--medium-gray); font-size: 0.9rem;">Dynamic range assessment with clipping detection</span>
+                        </div>
+                    </div>
+                    <div class="feature-item">
+                        <span class="feature-icon">▪</span>
+                        <div>
+                            <strong>Metadata Extraction</strong><br>
+                            <span style="color: var(--medium-gray); font-size: 0.9rem;">Complete EXIF data parsing including GPS coordinates</span>
+                        </div>
+                    </div>
+                    <div class="feature-item">
+                        <span class="feature-icon">▪</span>
+                        <div>
+                            <strong>Intelligent Scoring</strong><br>
+                            <span style="color: var(--medium-gray); font-size: 0.9rem;">Weighted algorithm with 65% pass threshold and partial credit</span>
+                        </div>
+                    </div>
+                </div>
+            </div>
+        </section>
+    </div>
+
+    <script>
+        const uploadArea = document.getElementById('uploadArea');
+        const fileInput = document.getElementById('fileInput');
+        const loading = document.getElementById('loading');
+        const results = document.getElementById('results');
+
+        // Upload area click
+        uploadArea.addEventListener('click', () => fileInput.click());
+
+        // Drag and drop
+        uploadArea.addEventListener('dragover', (e) => {
+            e.preventDefault();
+            uploadArea.classList.add('dragover');
+        });
+
+        uploadArea.addEventListener('dragleave', () => {
+            uploadArea.classList.remove('dragover');
+        });
+
+        uploadArea.addEventListener('drop', (e) => {
+            e.preventDefault();
+            uploadArea.classList.remove('dragover');
+            const file = e.dataTransfer.files[0];
+            if (file && file.type.startsWith('image/')) {
+                handleFileUpload(file);
+            }
+        });
+
+        // File input change
+        fileInput.addEventListener('change', (e) => {
+            const file = e.target.files[0];
+            if (file) {
+                handleFileUpload(file);
+            }
+        });
+
+        async function handleFileUpload(file) {
+            uploadArea.style.display = 'none';
+            loading.classList.add('show');
+            results.classList.remove('show');
+
+            const formData = new FormData();
+            formData.append('image', file);
+
+            try {
+                const response = await fetch('/api/validate', {
+                    method: 'POST',
+                    body: formData
+                });
+
+                const data = await response.json();
+                
+                loading.classList.remove('show');
+                displayResults(data);
+            } catch (error) {
+                loading.classList.remove('show');
+                alert('Error uploading image: ' + error.message);
+                uploadArea.style.display = 'block';
+            }
+        }
+
+        function displayResults(data) {
+            if (!data.success) {
+                alert('Validation failed: ' + data.message);
+                uploadArea.style.display = 'block';
+                return;
+            }
+
+            const summary = data.data.summary;
+            const checks = data.data.checks;
+
+            // Status badge
+            const statusBadge = document.getElementById('statusBadge');
+            const isPassing = summary.overall_status === 'pass';
+            statusBadge.innerHTML = `
+                <div class="status-badge ${isPassing ? 'pass' : 'fail'}">
+                    ${isPassing ? '✓' : '✕'} ${summary.overall_status.toUpperCase()} 
+                    (Score: ${summary.overall_score.toFixed(1)}%)
+                </div>
+            `;
+
+            // Validation cards
+            const grid = document.getElementById('validationGrid');
+            grid.innerHTML = '';
+
+            const checkLabels = {
+                blur: '🔍 Blur Detection',
+                brightness: '💡 Brightness',
+                resolution: '📏 Resolution',
+                exposure: '☀️ Exposure',
+                metadata: '📋 Metadata'
+            };
+
+            for (const [key, check] of Object.entries(checks)) {
+                const isPassing = check.status === 'pass';
+                const score = getScore(key, check);
+                const unit = key === 'resolution' ? ' MP' : '%';
+
+                const card = document.createElement('div');
+                card.className = `validation-card ${isPassing ? 'pass' : 'fail'}`;
+                card.innerHTML = `
+                    <h4>
+                        ${checkLabels[key] || key}
+                        <span style="margin-left: auto;">${isPassing ? '✓' : '✕'}</span>
+                    </h4>
+                    <div class="score">${score}${unit}</div>
+                    <p style="color: var(--gray-600); font-size: 0.9rem;">${check.reason || ''}</p>
+                `;
+                grid.appendChild(card);
+            }
+
+            // Recommendations
+            const recommendations = document.getElementById('recommendations');
+            if (summary.recommendations && summary.recommendations.length > 0) {
+                recommendations.innerHTML = `
+                    <h4 style="margin-top: 2rem; margin-bottom: 1rem;">Recommendations</h4>
+                    <ul style="padding-left: 1.5rem; color: var(--gray-600);">
+                        ${summary.recommendations.map(r => `<li>${r}</li>`).join('')}
+                    </ul>
+                `;
+            } else {
+                recommendations.innerHTML = '';
+            }
+
+            results.classList.add('show');
+        }
+
+        function getScore(checkType, check) {
+            switch(checkType) {
+                case 'blur':
+                    return check.score?.toFixed(0) || '--';
+                case 'brightness':
+                    return check.mean_brightness?.toFixed(0) || '--';
+                case 'resolution':
+                    return check.megapixels?.toFixed(1) || '--';
+                case 'exposure':
+                    return check.dynamic_range?.toFixed(0) || '--';
+                case 'metadata':
+                    return check.completeness?.toFixed(0) || '--';
+                default:
+                    return check.score?.toFixed(0) || '--';
+            }
+        }
+
+        function resetUpload() {
+            results.classList.remove('show');
+            uploadArea.style.display = 'block';
+            fileInput.value = '';
+        }
+
+        // Smooth scroll for navigation
+        document.querySelectorAll('a[href^="#"]').forEach(anchor => {
+            anchor.addEventListener('click', function (e) {
+                e.preventDefault();
+                const target = document.querySelector(this.getAttribute('href'));
+                if (target) {
+                    target.scrollIntoView({ behavior: 'smooth', block: 'start' });
+                }
+            });
+        });
+    </script>
+</body>
+</html>

templates/mobile_upload.html

@@ -1,624 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-    <meta charset="UTF-8">
-    <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <title>Civic Quality Control - Photo Upload</title>
-    <style>
-        * {
-            margin: 0;
-            padding: 0;
-            box-sizing: border-box;
-        }
-
-        body {
-            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
-            background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
-            min-height: 100vh;
-            display: flex;
-            align-items: center;
-            justify-content: center;
-            padding: 10px;
-        }
-
-        .container {
-            background: white;
-            border-radius: 20px;
-            box-shadow: 0 20px 40px rgba(0,0,0,0.1);
-            padding: 30px;
-            max-width: 500px;
-            width: 100%;
-            text-align: center;
-        }
-
-        .header {
-            margin-bottom: 30px;
-        }
-
-        .header h1 {
-            color: #333;
-            font-size: 28px;
-            margin-bottom: 10px;
-        }
-
-        .header p {
-            color: #666;
-            font-size: 16px;
-            line-height: 1.5;
-        }
-
-        .upload-section {
-            margin-bottom: 30px;
-        }
-
-        .camera-preview {
-            display: none;
-        }
-
-        #video {
-            width: 100%;
-            max-width: 400px;
-            border-radius: 15px;
-            margin-bottom: 20px;
-        }
-
-        #canvas {
-            display: none;
-        }
-
-        .captured-image {
-            max-width: 100%;
-            border-radius: 15px;
-            margin-bottom: 20px;
-            display: none;
-        }
-
-        .file-input-wrapper {
-            position: relative;
-            overflow: hidden;
-            display: inline-block;
-            width: 100%;
-            margin-bottom: 20px;
-        }
-
-        .file-input {
-            position: absolute;
-            left: -9999px;
-        }
-
-        .btn {
-            background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
-            color: white;
-            border: none;
-            padding: 15px 30px;
-            border-radius: 50px;
-            font-size: 16px;
-            font-weight: 600;
-            cursor: pointer;
-            transition: all 0.3s ease;
-            width: 100%;
-            margin-bottom: 15px;
-            display: flex;
-            align-items: center;
-            justify-content: center;
-            gap: 10px;
-        }
-
-        .btn:hover {
-            transform: translateY(-2px);
-            box-shadow: 0 10px 20px rgba(0,0,0,0.1);
-        }
-
-        .btn:active {
-            transform: translateY(0);
-        }
-
-        .btn.secondary {
-            background: #f8f9fa;
-            color: #333;
-            border: 2px solid #e9ecef;
-        }
-
-        .btn.danger {
-            background: #dc3545;
-        }
-
-        .btn:disabled {
-            opacity: 0.6;
-            cursor: not-allowed;
-            transform: none;
-        }
-
-        .loading {
-            display: none;
-            align-items: center;
-            justify-content: center;
-            gap: 10px;
-            margin: 20px 0;
-        }
-
-        .spinner {
-            width: 20px;
-            height: 20px;
-            border: 2px solid #f3f3f3;
-            border-top: 2px solid #667eea;
-            border-radius: 50%;
-            animation: spin 1s linear infinite;
-        }
-
-        @keyframes spin {
-            0% { transform: rotate(0deg); }
-            100% { transform: rotate(360deg); }
-        }
-
-        .results {
-            display: none;
-            text-align: left;
-            background: #f8f9fa;
-            padding: 20px;
-            border-radius: 15px;
-            margin-top: 20px;
-        }
-
-        .status-badge {
-            display: inline-block;
-            padding: 8px 16px;
-            border-radius: 20px;
-            font-size: 14px;
-            font-weight: 600;
-            margin-bottom: 15px;
-        }
-
-        .status-excellent { background: #d4edda; color: #155724; }
-        .status-good { background: #d1ecf1; color: #0c5460; }
-        .status-acceptable { background: #fff3cd; color: #856404; }
-        .status-rejected { background: #f8d7da; color: #721c24; }
-        .status-error { background: #f8d7da; color: #721c24; }
-
-        .validation-item {
-            margin-bottom: 15px;
-            padding: 12px;
-            background: white;
-            border-radius: 8px;
-            border-left: 4px solid #667eea;
-        }
-
-        .validation-item h4 {
-            margin-bottom: 5px;
-            color: #333;
-        }
-
-        .validation-item.error {
-            border-left-color: #dc3545;
-        }
-
-        .validation-item.warning {
-            border-left-color: #ffc107;
-        }
-
-        .validation-item.success {
-            border-left-color: #28a745;
-        }
-
-        .issues-list {
-            list-style: none;
-            margin: 10px 0;
-        }
-
-        .issues-list li {
-            padding: 5px 0;
-            border-bottom: 1px solid #eee;
-        }
-
-        .issues-list li:last-child {
-            border-bottom: none;
-        }
-
-        .metric {
-            display: flex;
-            justify-content: space-between;
-            margin-bottom: 8px;
-        }
-
-        .metric strong {
-            color: #333;
-        }
-
-        @media (max-width: 480px) {
-            .container {
-                padding: 20px;
-                margin: 10px;
-            }
-            
-            .header h1 {
-                font-size: 24px;
-            }
-            
-            .btn {
-                padding: 12px 20px;
-                font-size: 14px;
-            }
-        }
-    </style>
-</head>
-<body>
-    <div class="container">
-        <div class="header">
-            <h1>📸 Civic Quality Control</h1>
-            <p>Take or upload a photo to automatically check image quality for civic reporting</p>
-        </div>
-
-        <div class="upload-section">
-            <!-- Camera Preview -->
-            <div class="camera-preview" id="cameraPreview">
-                <video id="video" autoplay muted playsinline></video>
-                <canvas id="canvas"></canvas>
-                <img id="capturedImage" class="captured-image" alt="Captured photo">
-            </div>
-
-            <!-- File Input -->
-            <div class="file-input-wrapper" id="fileInputWrapper">
-                <input type="file" id="fileInput" class="file-input" accept="image/*" capture="environment">
-                <button class="btn" onclick="document.getElementById('fileInput').click()">
-                    📷 Take Photo or Upload Image
-                </button>
-            </div>
-
-            <!-- Action Buttons -->
-            <div id="actionButtons" style="display: none;">
-                <button class="btn" id="captureBtn" onclick="capturePhoto()">
-                    📸 Capture Photo
-                </button>
-                <button class="btn secondary" id="retakeBtn" onclick="retakePhoto()" style="display: none;">
-                    🔄 Retake Photo
-                </button>
-                <button class="btn secondary" id="stopCameraBtn" onclick="stopCamera()">
-                    ❌ Stop Camera
-                </button>
-            </div>
-
-            <!-- Process Button -->
-            <button class="btn" id="processBtn" onclick="processImage()" style="display: none;">
-                🔍 Analyze Photo Quality
-            </button>
-
-            <!-- Loading -->
-            <div class="loading" id="loading">
-                <div class="spinner"></div>
-                <span>Analyzing photo quality...</span>
-            </div>
-        </div>
-
-        <!-- Results -->
-        <div class="results" id="results">
-            <div id="resultsContent"></div>
-            <button class="btn secondary" onclick="resetApp()">
-                📷 Upload Another Photo
-            </button>
-        </div>
-    </div>
-
-    <script>
-        let stream = null;
-        let capturedImageData = null;
-
-        document.getElementById('fileInput').addEventListener('change', handleFileSelect);
-
-        function handleFileSelect(event) {
-            const file = event.target.files[0];
-            if (file) {
-                const reader = new FileReader();
-                reader.onload = function(e) {
-                    const img = document.getElementById('capturedImage');
-                    img.src = e.target.result;
-                    img.style.display = 'block';
-                    
-                    // Store the file for processing
-                    capturedImageData = file;
-                    
-                    // Show process button
-                    document.getElementById('processBtn').style.display = 'block';
-                    document.getElementById('fileInputWrapper').style.display = 'none';
-                };
-                reader.readAsDataURL(file);
-            }
-        }
-
-        async function startCamera() {
-            try {
-                stream = await navigator.mediaDevices.getUserMedia({ 
-                    video: { 
-                        facingMode: 'environment',  // Use back camera on mobile
-                        width: { ideal: 1920 },
-                        height: { ideal: 1080 }
-                    } 
-                });
-                
-                const video = document.getElementById('video');
-                video.srcObject = stream;
-                
-                document.getElementById('cameraPreview').style.display = 'block';
-                document.getElementById('fileInputWrapper').style.display = 'none';
-                document.getElementById('actionButtons').style.display = 'block';
-                
-            } catch (err) {
-                console.error('Error accessing camera:', err);
-                alert('Camera access failed. Please use file upload instead.');
-            }
-        }
-
-        function capturePhoto() {
-            const video = document.getElementById('video');
-            const canvas = document.getElementById('canvas');
-            const capturedImage = document.getElementById('capturedImage');
-            
-            canvas.width = video.videoWidth;
-            canvas.height = video.videoHeight;
-            
-            const ctx = canvas.getContext('2d');
-            ctx.drawImage(video, 0, 0);
-            
-            // Convert to blob
-            canvas.toBlob(function(blob) {
-                capturedImageData = new File([blob], 'captured_photo.jpg', { type: 'image/jpeg' });
-                
-                const imageUrl = URL.createObjectURL(blob);
-                capturedImage.src = imageUrl;
-                capturedImage.style.display = 'block';
-            }, 'image/jpeg', 0.9);
-            
-            // Hide video, show captured image
-            video.style.display = 'none';
-            document.getElementById('captureBtn').style.display = 'none';
-            document.getElementById('retakeBtn').style.display = 'block';
-            document.getElementById('processBtn').style.display = 'block';
-        }
-
-        function retakePhoto() {
-            const video = document.getElementById('video');
-            const capturedImage = document.getElementById('capturedImage');
-            
-            video.style.display = 'block';
-            capturedImage.style.display = 'none';
-            
-            document.getElementById('captureBtn').style.display = 'block';
-            document.getElementById('retakeBtn').style.display = 'none';
-            document.getElementById('processBtn').style.display = 'none';
-            
-            capturedImageData = null;
-        }
-
-        function stopCamera() {
-            if (stream) {
-                stream.getTracks().forEach(track => track.stop());
-                stream = null;
-            }
-            
-            document.getElementById('cameraPreview').style.display = 'none';
-            document.getElementById('actionButtons').style.display = 'none';
-            document.getElementById('fileInputWrapper').style.display = 'block';
-            document.getElementById('processBtn').style.display = 'none';
-        }
-
-        async function processImage() {
-            if (!capturedImageData) {
-                alert('No image to process');
-                return;
-            }
-
-            // Show loading
-            document.getElementById('loading').style.display = 'flex';
-            document.getElementById('processBtn').style.display = 'none';
-
-            try {
-                const formData = new FormData();
-                formData.append('image', capturedImageData);
-
-                const response = await fetch('/api/upload', {
-                    method: 'POST',
-                    body: formData
-                });
-
-                const result = await response.json();
-                
-                // Hide loading
-                document.getElementById('loading').style.display = 'none';
-                
-                // Show results
-                displayResults(result);
-
-            } catch (error) {
-                console.error('Error processing image:', error);
-                document.getElementById('loading').style.display = 'none';
-                alert('Failed to process image. Please try again.');
-                document.getElementById('processBtn').style.display = 'block';
-            }
-        }
-
-        function displayResults(result) {
-            const resultsDiv = document.getElementById('results');
-            const contentDiv = document.getElementById('resultsContent');
-            
-            if (!result.success) {
-                contentDiv.innerHTML = `
-                    <div class="status-badge status-error">❌ Error</div>
-                    <p><strong>Error:</strong> ${result.message}</p>
-                `;
-                resultsDiv.style.display = 'block';
-                return;
-            }
-
-            const data = result.data;
-            const statusClass = `status-${data.overall_status.replace('_', '-')}`;
-            const statusEmoji = getStatusEmoji(data.overall_status);
-            
-            let html = `
-                <div class="status-badge ${statusClass}">
-                    ${statusEmoji} ${data.overall_status.replace('_', ' ').toUpperCase()}
-                </div>
-                <div class="metric">
-                    <span>Processing Time:</span>
-                    <strong>${data.processing_time_seconds}s</strong>
-                </div>
-            `;
-
-            // Add validation results
-            const validations = data.validations || {};
-            
-            // Blur Detection
-            if (validations.blur_detection && !validations.blur_detection.error) {
-                const blur = validations.blur_detection;
-                html += `
-                    <div class="validation-item ${blur.is_blurry ? 'error' : 'success'}">
-                        <h4>🔍 Blur Detection</h4>
-                        <div class="metric">
-                            <span>Blur Score:</span>
-                            <strong>${blur.blur_score}</strong>
-                        </div>
-                        <div class="metric">
-                            <span>Quality:</span>
-                            <strong>${blur.quality}</strong>
-                        </div>
-                    </div>
-                `;
-            }
-
-            // Brightness Validation
-            if (validations.brightness_validation && !validations.brightness_validation.error) {
-                const brightness = validations.brightness_validation;
-                html += `
-                    <div class="validation-item ${brightness.has_brightness_issues ? 'error' : 'success'}">
-                        <h4>💡 Brightness</h4>
-                        <div class="metric">
-                            <span>Mean Brightness:</span>
-                            <strong>${brightness.mean_brightness}</strong>
-                        </div>
-                        <div class="metric">
-                            <span>Quality Score:</span>
-                            <strong>${(brightness.quality_score * 100).toFixed(1)}%</strong>
-                        </div>
-                    </div>
-                `;
-            }
-
-            // Resolution Check
-            if (validations.resolution_check && !validations.resolution_check.error) {
-                const resolution = validations.resolution_check;
-                html += `
-                    <div class="validation-item ${resolution.meets_min_resolution ? 'success' : 'error'}">
-                        <h4>📏 Resolution</h4>
-                        <div class="metric">
-                            <span>Dimensions:</span>
-                            <strong>${resolution.width} × ${resolution.height}</strong>
-                        </div>
-                        <div class="metric">
-                            <span>Megapixels:</span>
-                            <strong>${resolution.megapixels} MP</strong>
-                        </div>
-                        <div class="metric">
-                            <span>Quality Tier:</span>
-                            <strong>${resolution.quality_tier}</strong>
-                        </div>
-                    </div>
-                `;
-            }
-
-            // Exposure Check
-            if (validations.exposure_check && !validations.exposure_check.error) {
-                const exposure = validations.exposure_check;
-                html += `
-                    <div class="validation-item ${exposure.has_good_exposure ? 'success' : 'warning'}">
-                        <h4>☀️ Exposure</h4>
-                        <div class="metric">
-                            <span>Quality:</span>
-                            <strong>${exposure.exposure_quality}</strong>
-                        </div>
-                        <div class="metric">
-                            <span>Dynamic Range:</span>
-                            <strong>${exposure.dynamic_range}</strong>
-                        </div>
-                    </div>
-                `;
-            }
-
-            // Issues
-            if (data.issues && data.issues.length > 0) {
-                html += `
-                    <div class="validation-item error">
-                        <h4>⚠️ Issues Found</h4>
-                        <ul class="issues-list">
-                `;
-                data.issues.forEach(issue => {
-                    html += `<li><strong>${issue.type}:</strong> ${issue.message}</li>`;
-                });
-                html += `</ul></div>`;
-            }
-
-            // Recommendations
-            if (data.recommendations && data.recommendations.length > 0) {
-                html += `
-                    <div class="validation-item">
-                        <h4>💡 Recommendations</h4>
-                        <ul class="issues-list">
-                `;
-                data.recommendations.forEach(rec => {
-                    html += `<li>${rec}</li>`;
-                });
-                html += `</ul></div>`;
-            }
-
-            contentDiv.innerHTML = html;
-            resultsDiv.style.display = 'block';
-        }
-
-        function getStatusEmoji(status) {
-            const emojis = {
-                'excellent': '🌟',
-                'good': '✅',
-                'acceptable': '⚠️',
-                'needs_improvement': '📈',
-                'rejected': '❌',
-                'error': '💥'
-            };
-            return emojis[status] || '❓';
-        }
-
-        function resetApp() {
-            // Reset all states
-            capturedImageData = null;
-            
-            // Hide all sections
-            document.getElementById('cameraPreview').style.display = 'none';
-            document.getElementById('actionButtons').style.display = 'none';
-            document.getElementById('processBtn').style.display = 'none';
-            document.getElementById('results').style.display = 'none';
-            document.getElementById('loading').style.display = 'none';
-            
-            // Show file input
-            document.getElementById('fileInputWrapper').style.display = 'block';
-            
-            // Reset captured image
-            const capturedImage = document.getElementById('capturedImage');
-            capturedImage.style.display = 'none';
-            capturedImage.src = '';
-            
-            // Reset file input
-            document.getElementById('fileInput').value = '';
-            
-            // Stop camera if running
-            stopCamera();
-        }
-
-        // Add button to start camera if supported
-        if (navigator.mediaDevices && navigator.mediaDevices.getUserMedia) {
-            const startCameraBtn = document.createElement('button');
-            startCameraBtn.className = 'btn secondary';
-            startCameraBtn.innerHTML = '📹 Use Camera';
-            startCameraBtn.onclick = startCamera;
-            
-            const fileWrapper = document.getElementById('fileInputWrapper');
-            fileWrapper.parentNode.insertBefore(startCameraBtn, fileWrapper.nextSibling);
-        }
-    </script>
-</body>
-</html>

templates/redoc.html

@@ -0,0 +1,70 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>PhotoGuard API Reference - ReDoc</title>
+    <style>
+        body {
+            margin: 0;
+            padding: 0;
+        }
+    </style>
+</head>
+<body>
+    <redoc spec-url="/api/openapi.json" 
+           hide-download-button="false"
+           suppress-warnings="true"
+           scroll-y-offset="0"
+           native-scrollbars="true"
+           theme='{
+               "colors": {
+                   "primary": {
+                       "main": "#000000"
+                   },
+                   "success": {
+                       "main": "#2d2d2d"
+                   },
+                   "text": {
+                       "primary": "#1a1a1a",
+                       "secondary": "#6b6b6b"
+                   },
+                   "http": {
+                       "get": "#6b6b6b",
+                       "post": "#000000",
+                       "put": "#2d2d2d",
+                       "delete": "#8b0000"
+                   }
+               },
+               "typography": {
+                   "fontSize": "14px",
+                   "lineHeight": "1.6em",
+                   "fontFamily": "-apple-system, BlinkMacSystemFont, \"Segoe UI\", Roboto, \"Helvetica Neue\", Arial, sans-serif",
+                   "headings": {
+                       "fontFamily": "-apple-system, BlinkMacSystemFont, \"Segoe UI\", Roboto, \"Helvetica Neue\", Arial, sans-serif",
+                       "fontWeight": "600"
+                   },
+                   "code": {
+                       "fontSize": "13px",
+                       "fontFamily": "\"Source Code Pro\", Monaco, Consolas, monospace",
+                       "backgroundColor": "#f5f5f5",
+                       "color": "#1a1a1a"
+                   }
+               },
+               "sidebar": {
+                   "backgroundColor": "#ffffff",
+                   "textColor": "#1a1a1a",
+                   "activeTextColor": "#000000",
+                   "groupItems": {
+                       "textTransform": "uppercase"
+                   }
+               },
+               "rightPanel": {
+                   "backgroundColor": "#1a1a1a",
+                   "textColor": "#f5f5f5"
+               }
+           }'>
+    </redoc>
+    <script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"></script>
+</body>
+</html>

templates/swagger.html

@@ -0,0 +1,96 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>PhotoGuard API Documentation - Swagger UI</title>
+    <link rel="stylesheet" type="text/css" href="https://unpkg.com/swagger-ui-dist@5.10.5/swagger-ui.css">
+    <style>
+        body {
+            margin: 0;
+            padding: 0;
+            background-color: #f5f5f5;
+        }
+        
+        .topbar {
+            background-color: #000000 !important;
+            padding: 10px 0;
+        }
+        
+        .topbar-wrapper .link {
+            color: #ffffff !important;
+        }
+        
+        .swagger-ui .info .title {
+            color: #1a1a1a;
+        }
+        
+        .swagger-ui .opblock.opblock-post {
+            border-color: #000000;
+            background: rgba(0, 0, 0, 0.05);
+        }
+        
+        .swagger-ui .opblock.opblock-post .opblock-summary-method {
+            background: #000000;
+        }
+        
+        .swagger-ui .opblock.opblock-get {
+            border-color: #6b6b6b;
+            background: rgba(107, 107, 107, 0.05);
+        }
+        
+        .swagger-ui .opblock.opblock-get .opblock-summary-method {
+            background: #6b6b6b;
+        }
+        
+        .swagger-ui .opblock-tag {
+            border-bottom: 2px solid #cccccc;
+            color: #1a1a1a;
+        }
+        
+        .swagger-ui .btn.execute {
+            background-color: #000000;
+            border-color: #000000;
+            color: #ffffff;
+        }
+        
+        .swagger-ui .btn.execute:hover {
+            background-color: #2d2d2d;
+            border-color: #2d2d2d;
+        }
+        
+        .swagger-ui .scheme-container {
+            background-color: #ffffff;
+            box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
+        }
+    </style>
+</head>
+<body>
+    <div id="swagger-ui"></div>
+    <script src="https://unpkg.com/swagger-ui-dist@5.10.5/swagger-ui-bundle.js"></script>
+    <script src="https://unpkg.com/swagger-ui-dist@5.10.5/swagger-ui-standalone-preset.js"></script>
+    <script>
+        window.onload = function() {
+            window.ui = SwaggerUIBundle({
+                url: "/api/openapi.json",
+                dom_id: '#swagger-ui',
+                deepLinking: true,
+                presets: [
+                    SwaggerUIBundle.presets.apis,
+                    SwaggerUIStandalonePreset
+                ],
+                plugins: [
+                    SwaggerUIBundle.plugins.DownloadUrl
+                ],
+                layout: "StandaloneLayout",
+                defaultModelsExpandDepth: 1,
+                defaultModelExpandDepth: 3,
+                docExpansion: "list",
+                filter: true,
+                showRequestHeaders: true,
+                tryItOutEnabled: true
+            });
+        };
+    </script>
+</body>
+</html>

tests/test_api_endpoints.py

@@ -1,24 +1,63 @@
+import io
+
 import pytest
-from flask import Flask
-from app import app  # Import the Flask app
+from PIL import Image
+
+from app import create_app
+
 
 @pytest.fixture
-def client():
-    """Test client for the Flask app."""
-    app.config['TESTING'] = True
+def client(tmp_path):
+    """Configure an isolated Flask test client per test run."""
+    app = create_app('testing')
+
+    upload_dir = tmp_path / 'uploads'
+    processed_dir = tmp_path / 'processed'
+    rejected_dir = tmp_path / 'rejected'
+    for directory in (upload_dir, processed_dir, rejected_dir):
+        directory.mkdir(parents=True, exist_ok=True)
+
+    app.config.update({
+        'UPLOAD_FOLDER': str(upload_dir),
+        'PROCESSED_FOLDER': str(processed_dir),
+        'REJECTED_FOLDER': str(rejected_dir),
+    })
+
     with app.test_client() as client:
         yield client
 
-def test_check_quality_no_image(client):
-    """Test check_quality endpoint with no image."""
-    response = client.post('/check_quality')
+
+def test_health_endpoint(client):
+    response = client.get('/api/health')
+    assert response.status_code == 200
+    payload = response.get_json()
+    assert payload['success'] is True
+    assert payload['data']['status'] == 'healthy'
+
+
+def test_validate_endpoint_without_file(client):
+    response = client.post('/api/validate')
     assert response.status_code == 400
-    data = response.get_json()
-    assert 'error' in data
-    assert data['error'] == 'No image uploaded'
-
-def test_check_quality_with_image(client, sample_image):
-    """Test check_quality endpoint with a sample image."""
-    # This would need actual image data
-    # For now, just test the structure
-    pass
+    payload = response.get_json()
+    assert payload['success'] is False
+    assert 'No image file provided' in payload['message']
+
+
+def test_validate_endpoint_with_generated_image(client):
+    image = Image.new('RGB', (1024, 768), color=(180, 180, 180))
+    buffer = io.BytesIO()
+    image.save(buffer, format='JPEG')
+    buffer.seek(0)
+
+    response = client.post(
+        '/api/validate',
+        data={'image': (buffer, 'sample.jpg')},
+        content_type='multipart/form-data'
+    )
+
+    # Validation may return 200 for pass/fail; ensure we get a structured payload.
+    assert response.status_code == 200
+    payload = response.get_json()
+    assert payload['success'] is True
+    assert 'summary' in payload['data']
+    assert 'checks' in payload['data']