docs/ARCHITECTURE.md

Architecture Documentation

Table of Contents

1. System Overview
2. Overall Architecture
3. Data Pipeline
4. Component Details
5. Product Architecture
6. Technology Stack

---

System Overview

AI Image Screener is a multi-tier screening system designed for first-pass screening of potentially AI-generated images in production workflows. The system combines quantitative statistical metrics (Tier-1) with declarative evidence analyzers (Tier-2) and resolves them through a deterministic decision policy to produce review-aware, multi-class verdicts with full explainability.

The system is explicitly not a ground-truth detector and is designed for human-in-the-loop workflows.

Design Principles:

• No single metric dominates decisions
• All intermediate data preserved for explainability
• Parallel processing for batch efficiency
• Zero external ML model dependencies
• Transparent, auditable decision logic
• Separation of quantitative metrics and declarative evidence
• Deterministic policy-based decision resolution

---

Overall Architecture

graph TB
    subgraph "Frontend Layer"
        UI["Web UI<br/>Single Page HTML"]
    end
    
    subgraph "API Layer"
        API["FastAPI Server<br/>app.py"]
        CORS["CORS Middleware"]
        ERROR["Global Error Handler"]
    end
    
    subgraph "Processing Layer"
        VALIDATOR["Image Validator<br/>utils/validators.py"]
        BATCH["Batch Processor<br/>features/batch_processor.py"]
    end
    
    subgraph "Detection Layer — Tier 1"
        AGG["Signal Aggregator<br/>metrics/signal_aggregator.py"]
        
        subgraph "Independent Metrics"
            M1["Gradient PCA"]
            M2["Frequency FFT"]
            M3["Noise Pattern"]
            M4["Texture Stats"]
            M5["Color Distribution"]
        end
    end
    
    subgraph "Evidence Layer — Tier 2 (non-scoring)"
        EVIDENCE_AGG["Evidence Aggregator (Tier-2)<br/>evidence_analyzers/"]
        EXIF["EXIF Analyzer"]
        WM["Watermark Analyzer"]
    end
    
    subgraph "Decision Layer"
        POLICY["Decision Policy Engine<br/>decision_policy.py"]
        DETAIL["Decision Explanation Engine"]
    end
    
    subgraph "Reporting Layer"
        CSV["CSV Reporter"]
        JSON["JSON Reporter"]
    end
    
    subgraph "Storage Layer"
        UPLOAD[("Temp Uploads")]
        CACHE[("Processing Cache")]
        REPORTS[("Reports")]
    end
    
    UI --> API
    API --> VALIDATOR
    VALIDATOR --> BATCH
    API --> ERROR
    
    BATCH --> AGG
    AGG --> M1 & M2 & M3 & M4 & M5
    M1 & M2 & M3 & M4 & M5 --> AGG
    
    BATCH --> EVIDENCE_AGG
    EVIDENCE_AGG --> EXIF & WM
    
    AGG --> POLICY
    EVIDENCE_AGG --> DETAIL
    EVIDENCE_AGG --> POLICY
    
    POLICY --> DETAIL
    DETAIL --> CSV & JSON
    
    API -.-> UPLOAD
    BATCH -.-> CACHE
    CSV & JSON -.-> REPORTS

---

Data Pipeline

flowchart LR
    subgraph "Input"
        A[Image Upload] --> B{Validation}
        B -->|Pass| C[Temp Storage]
        B -->|Fail| X[Error Response]
    end
    
    subgraph "Preprocessing"
        C --> D[Load Image]
        D --> E[Resize / Normalize]
        E --> F[Luminance Conversion]
    end
    
    subgraph "Tier 1 — Statistical Metrics"
        F --> G1[Gradient Analysis]
        F --> G2[Frequency Analysis]
        F --> G3[Noise Analysis]
        F --> G4[Texture Analysis]
        F --> G5[Color Analysis]
    end
    
    subgraph "Metric Aggregation"
        G1 & G2 & G3 & G4 & G5 --> H[Weighted Ensemble]
        H --> I[Overall Score<br/>0.0 – 1.0]
        I --> J[Detection Status]
    end
    
    subgraph "Tier 2 — Declarative Evidence"
        C --> K1[EXIF Analysis]
        C --> K2[Watermark Analysis]
        K1 & K2 --> L[Evidence Results]
    end
    
    subgraph "Decision Policy"
        J --> M[Rule-Based Engine]
        L --> M
        M --> V1[Mostly Authentic]
        M --> V2[Authentic But Review]
        M --> V3[Suspicious AI Likely]
        M --> V4[Confirmed AI Generated]
    end
    
    subgraph "Output"
        M --> N[Detailed Result Assembly]
        N --> O[Explainability]
        O --> P[CSV / JSON Export]
    end

---

Component Details

1. Configuration Layer (config/)

classDiagram
    class Settings {
        +str APP_NAME
        +float REVIEW_THRESHOLD
        +dict METRIC_WEIGHTS
        +int MAX_WORKERS
        +get_metric_weights()
        +_validate_weights()
    }
    
    class Constants {
        <<enumeration>>
        +MetricType
        +SignalStatus
        +FinalDecision
        +SIGNAL_THRESHOLDS
        +METRIC_EXPLANATIONS
    }
    
    class Schemas {
        +MetricResult
        +DetectionSignal
        +AnalysisResult
        +BatchAnalysisResult
    }
    
    Settings --> Constants: uses
    Schemas --> Constants: references

Key Configuration Files:

• settings.py: Runtime settings, environment variables, validation
• constants.py: Enums, thresholds, metric parameters, explanations
• schemas.py: Pydantic models for type safety and validation

---

2. Metrics Layer (metrics/)

graph TD
    subgraph "Gradient-Field PCA"
        A1[RGB → Luminance] --> A2[Sobel Gradients]
        A2 --> A3[Sample Vectors<br/>n=10000]
        A3 --> A4[PCA Analysis]
        A4 --> A5[Eigenvalue Ratio]
        A5 --> A6{Ratio < 0.85?}
        A6 -->|Yes| A7[High Suspicion]
        A6 -->|No| A8[Low Suspicion]
    end
    
    subgraph "Frequency Analysis"
        B1[Luminance] --> B2[2D FFT]
        B2 --> B3[Radial Spectrum<br/>64 bins]
        B3 --> B4[HF Energy Ratio]
        B4 --> B5[Spectral Roughness]
        B5 --> B6[Power Law Deviation]
        B6 --> B7[Weighted Anomaly]
    end
    
    subgraph "Noise Analysis"
        C1[Luminance] --> C2[Extract Patches<br/>32×32, stride=16]
        C2 --> C3[Laplacian Filter]
        C3 --> C4[MAD Estimation]
        C4 --> C5[CV Analysis]
        C5 --> C6[IQR Analysis]
        C6 --> C7[Uniformity Score]
    end
    
    style A1 fill:#ffe1e1
    style B1 fill:#e1e1ff
    style C1 fill:#e1ffe1

Metric Weights (Default):

Gradient:  30%
Frequency: 25%
Noise:     20%
Texture:   15%
Color:     10%

3. Evidence Layer (evidence_analyzers/)

The Evidence Layer performs Tier-2 analysis using non-scoring, declarative analyzers that inspect metadata and embedded artifacts.

Evidence analyzers do not produce numeric scores. Instead, they emit directional findings that either support authenticity, indicate AI generation, or remain indeterminate.

Evidence Outputs:

• direction: AUTHENTIC | AI_GENERATED | INDETERMINATE
• finding: Human-readable explanation
• confidence: Optional (0.0–1.0)

Current Evidence Analyzers:

• EXIF Analyzer — metadata presence, consistency, plausibility
• Watermark Analyzer — detection of known or statistical AI watermark patterns

---

4. Processing Pipeline

sequenceDiagram
    participant UI
    participant API
    participant BatchProcessor
    participant MetricsAggregator
    participant EvidenceAggregator
    participant DecisionPolicy
    participant Reporter
    
    UI->>API: Upload Images
    API->>BatchProcessor: process_batch()
    
    loop For each image
        BatchProcessor->>MetricsAggregator: analyze_image()
        par Metrics
            MetricsAggregator->>MetricsAggregator: run all detectors
        end
        
        BatchProcessor->>EvidenceAggregator: analyze(image_path)
        EvidenceAggregator-->>BatchProcessor: evidence[]
        
        MetricsAggregator-->>DecisionPolicy: metric results + status
        EvidenceAggregator-->>DecisionPolicy: evidence results
        
        DecisionPolicy-->>BatchProcessor: final decision
        BatchProcessor-->>UI: progress update
    end
    
    BatchProcessor->>Reporter: generate reports
    Reporter-->>API: BatchAnalysisResult
    API-->>UI: JSON response

---

5. Metric Execution Detail

flowchart TB
    A[RGB Image] --> B[Preprocessing]
    B --> C[Feature Extraction]
    
    C --> D1[Sub-metric A]
    C --> D2[Sub-metric B]
    C --> D3[Sub-metric C]
    
    D1 --> E1[Score A]
    D2 --> E2[Score B]
    D3 --> E3[Score C]
    
    E1 & E2 & E3 --> F[Weighted Metric Score]
    F --> G[Confidence Estimation]
    G --> H[MetricResult]
    H --> I{Valid?}
    
    I -->|Yes| J[Return Result]
    I -->|No| K[Neutral Output]

Example: Noise Analysis Sub-metrics

• CV Anomaly: 40% weight
• Noise Level Anomaly: 40% weight
• IQR Anomaly: 20% weight

---

Product Architecture

graph TB
    subgraph "Interfaces"
        WEB[Web UI]
        API_CLIENT[API Clients]
    end
    
    subgraph "Core Engine"
        METRICS[Tier-1 Metrics Engine]
        EVIDENCE[Tier-2 Evidence Engine]
        POLICY[Decision Policy]
    end
    
    subgraph "Reporting"
        DETAIL[Detailed Analysis]
        EXPORT[CSV / JSON Export]
    end
    
    subgraph "Use Cases"
        UC1[Moderation Pipelines]
        UC2[Journalism Verification]
        UC3[Stock Media Review]
        UC4[Compliance Workflows]
    end
    
    WEB --> METRICS
    API_CLIENT --> METRICS
    
    METRICS --> POLICY
    EVIDENCE --> POLICY
    
    POLICY --> DETAIL
    DETAIL --> EXPORT
    
    EXPORT -.-> UC1 & UC2 & UC3 & UC4

---

Technology Stack

graph LR
    subgraph "Backend"
        B1[Python 3.11+]
        B2[FastAPI]
        B3[Pydantic]
        B4[NumPy/SciPy]
        B5[OpenCV]
        B6[Pillow]
    end
    
    subgraph "Frontend"
        F1[HTML5]
        F2[Vanilla JavaScript]
        F3[CSS3]
    end
    
    subgraph "Reporting"
        R2[CSV stdlib]
        R3[JSON stdlib]
    end
    
    subgraph "Infrastructure"
        I1[Uvicorn ASGI]
        I2[File-based Storage]
        I3[In-memory Sessions]
    end
    
    B2 --> B1
    B3 --> B1
    B4 --> B1
    B5 --> B1
    B6 --> B1
    
    F1 --> F2
    F2 --> F3
    
    R2 --> B1
    R3 --> B1
    
    I1 --> B2
    I2 --> B1
    I3 --> B2
    
    style B1 fill:#3776ab
    style B2 fill:#009688
    style F1 fill:#e34c26
    style F2 fill:#f0db4f

Key Dependencies:

• FastAPI: Async API framework
• NumPy/SciPy: Numerical computation
• OpenCV: Image processing and filtering
• Pillow: Image loading and validation
• Pydantic: Data validation and serialization

---

Performance Characteristics

Processing Times (Average)

• Single image analysis: 2-4 seconds
• Batch processing (10 images): 15-25 seconds (parallel)
• Report generation: 1-3 seconds

Resource Usage

• Memory per image: 50-150 MB
• Max concurrent workers: 4 (configurable)
• Temp storage: ~10 MB per image

Scalability Considerations

• Current: Single-server deployment
• Bottleneck: CPU-bound metric computation
• Future: Distributed processing via task queue (Celery/RabbitMQ)

---

Security & Privacy

1. No data persistence: Uploaded images deleted after processing
2. Local processing: No external API calls
3. Stateless design: No user tracking
4. Input validation: File type, size, dimension checks
5. Timeout protection: 30s per-image limit

---

Deployment Architecture

graph TB
    CLIENT[Clients] --> LB[Load Balancer]
    
    subgraph "Application Tier"
        APP1[FastAPI Instance]
        APP2[FastAPI Instance]
    end
    
    subgraph "Storage"
        FS[File Storage<br/>uploads / reports]
    end
    
    subgraph "Observability"
        LOGS[Central Logs]
        METRICS[Metrics]
    end
    
    LB --> APP1
    LB --> APP2
    
    APP1 -.-> FS
    APP2 -.-> FS
    
    APP1 -.-> LOGS
    APP2 -.-> LOGS
    
    APP1 -.-> METRICS
    APP2 -.-> METRICS

Recommended Setup:

• Web Server: Nginx (reverse proxy)
• App Server: Uvicorn (ASGI)
• Process Manager: Systemd or Supervisor
• Monitoring: Prometheus + Grafana
• Logging: Structured JSON logs to ELK stack

---

Future Architecture Considerations

1. Message Queue Integration: Redis/RabbitMQ for async processing
2. Database Layer: PostgreSQL for result persistence and analytics
3. Caching Layer: Redis for threshold/config caching
4. Distributed Storage: S3-compatible storage for reports
5. API Gateway: Kong/Tyk for rate limiting and auth

---

Document Version: 1.0
Last Updated: December 2025
Architecture by: Satyaki Mitra