AI Shield – Enterprise Deepfake & Digital Media Authenticity Verification Platform

AI Shield is a production-ready, enterprise-grade full-stack platform designed to detect and verify deepfakes, AI-generated images, and manipulated digital media. The platform combines state-of-the-art vision-language models (SigLIP) with digital image forensics (Error Level Analysis (ELA), Grad-CAM Heatmaps, and Metadata Extraction) to provide explainable, high-confidence authenticity assessments.

---

🌟 Executive Overview & Key Features

• Enterprise-Grade Full-Stack Architecture: Strictly decoupled frontend SPA and backend REST/WebSocket API adhering to clean software engineering principles (Single Responsibility Principle, Repository Pattern, Service Layer Architecture).
• Explainable AI Pipeline:
  • SigLIP Vision-Language Classifier: Deep neural network inference trained to classify media as Authentic or AI-Generated.
  • Error Level Analysis (ELA): Compression forensic technique highlighting areas of digital manipulation and resaving discrepancies.
  • Grad-CAM Heatmap Visualization: Visual explanation layer mapping activation gradients onto uploaded images to show exactly which pixel regions triggered the AI's prediction.
  • Metadata Forensics: Extraction and verification of EXIF tags, creation dates, software signatures, and camera sensor parameters.
• 100% UI/UX Fidelity: Preserves a stunning, modern dark-mode aesthetic with glassmorphism, Framer Motion micro-animations, and responsive shadcn/ui components.
• Real-Time Progress Streaming: WebSocket communication streaming granular step-by-step processing status directly to the user interface.
• Hackathon & Demo Readiness: Out-of-the-box zero-configuration Demo Mode (DEMO_MODE=true) automatically seeds a demo admin account ([email protected] / demo) and provides graceful AI fallback inference if custom model weights are absent.

---

🏗️ System Architecture

AI Shield is structured into two autonomous, highly scalable components:

+-----------------------------------------------------------------------------------+
|                              FRONTEND CLIENT (Vite SPA)                           |
|  React 19 | TypeScript | Tailwind CSS v4 | TanStack Router & Query | Zustand      |
+-----------------------------------------------------------------------------------+
       | (REST HTTP API - Axios + JWT Auth)         ^ (Real-Time Progress Stream)
       v                                            | (WebSockets - Async)
+-----------------------------------------------------------------------------------+
|                            BACKEND SERVER (FastAPI Python)                        |
|  +--------------------+  +--------------------+  +-----------------------------+  |
|  |   API Layer (v1)   |  |   Service Layer    |  | Repository Layer (SQLAlchemy)|  |
|  +--------------------+  +--------------------+  +-----------------------------+  |
+-----------------------------------------------------------------------------------+
       | (Async Tasks)                              | (Async ORM Access)
       v                                            v
+-----------------------------------------------------------------------------------+
|                        AI FORENSIC & INFERENCE ENGINE                             |
|  SigLIP Detector (Hugging Face) | ELA Compression | Grad-CAM Overlay | EXIF Parser       |
+-----------------------------------------------------------------------------------+
                                                    | (SQLAlchemy / Alembic)
                                                    v
                                       +-------------------------+
                                       | SQLite / PostgreSQL DB  |
                                       +-------------------------+

---

📂 Enterprise Folder Structure

d:/Deepfake/
├── backend/                  # Python FastAPI Backend API
│   ├── alembic/              # Database Migrations (Alembic)
│   ├── app/
│   │   ├── api/v1/           # REST Endpoints (auth, users, analysis, dashboard, ws, etc.)
│   │   ├── core/             # Infrastructure (config, db, security, logging, exceptions)
│   │   ├── models/           # SQLAlchemy Async ORM Models
│   │   ├── schemas/          # Pydantic v2 Validation Schemas
│   │   ├── repositories/     # Data Access Layer (Repository Pattern)
│   │   ├── services/         # Business Logic Layer
│   │   └── tasks/            # Asynchronous Background Processing
│   ├── ai/                   # AI Detection Modules
│   │   ├── inference/        # SigLIP Detector & Fallback
│   │   ├── forensics/        # ELA & Metadata Extraction
│   │   ├── gradcam/          # Heatmap Generator
│   │   └── pipeline.py       # Unified AI Orchestrator
│   ├── uploads/              # Media Storage (Uploaded, ELA, GradCAM, Reports)
│   ├── requirements.txt      # Python Dependencies
│   └── seed.py               # Database Demo Seeder
├── frontend/                 # React 19 + TypeScript + Vite SPA
│   ├── src/
│   │   ├── components/       # Layout, Common & shadcn/ui Primitives
│   │   ├── features/         # Feature Modules (auth, dashboard, upload, results, history, etc.)
│   │   ├── hooks/            # Custom React Hooks (WebSockets, progress, mobile)
│   │   ├── layouts/          # Layout Wrappers (Sidebar, Header, BackgroundGlow)
│   │   ├── lib/              # Axios Client, Utility classes & Error Handling
│   │   ├── routes/           # TanStack Type-Safe Route Definitions
│   │   ├── services/         # REST API Service Connectors
│   │   └── stores/           # Zustand Client State Management
│   ├── package.json
│   └── vite.config.ts
├── docs/                     # Comprehensive Technical Documentation Suite
│   ├── ARCHITECTURE.md       # High-Level Architecture & Design Patterns
│   ├── API_DOCUMENTATION.md  # Exhaustive REST API Specification
│   ├── DATABASE_SCHEMA.md    # ER Diagram, Models & Migration Guide
│   ├── AI_PIPELINE.md        # SigLIP, ELA & Grad-CAM Specifications
│   ├── UPLOAD_RESULT_FLOW.md # Ingestion to Report Sequence Diagrams
│   ├── WEBSOCKET_EVENTS.md   # Real-Time WebSocket Streaming Protocol
│   └── PROJECT_REPORT.md     # Comprehensive Project Evaluation Report
├── .env.example              # Centralized Environment Variables Example
├── docker-compose.yml        # Multi-Container Deployment Configuration
└── README.md                 # Project Overview & Quickstart Guide

---

🚀 Quickstart Guide

1. Prerequisites

• Node.js (v20+ recommended) & npm
• Python (v3.10+ recommended)
• Git

2. Backend Setup

# Navigate to backend directory
cd backend

# Create virtual environment
python -m venv venv

# Activate virtual environment (Windows Powershell)
.\venv\Scripts\Activate.ps1

# Install dependencies
pip install -r requirements.txt

# Run database migrations
alembic upgrade head

# Seed demo user account ([email protected] / demo)
python seed.py

# Start FastAPI development server
uvicorn app.main:app --reload --port 8000

3. Frontend Setup

# Open a new terminal and navigate to frontend directory
cd frontend

# Install Node dependencies
npm install

# Start Vite development server
npm run dev

The application will be accessible at http://localhost:5173. Sign in with [email protected] and password demo.

---

🛠️ Tech Stack

Frontend

• Framework: React 19 + Vite
• Language: TypeScript 5.8+
• Routing: TanStack Router
• State Management: Zustand
• Data Fetching: Axios + TanStack Query
• Styling: Tailwind CSS v4 + shadcn/ui + Framer Motion
• Icons: Lucide React
• Charts: Recharts

Backend

• Framework: FastAPI (Python 3.10+)
• Database: SQLite (PostgreSQL compatible)
• ORM: SQLAlchemy (Async) + Alembic
• Validation: Pydantic v2
• Auth: JWT (JSON Web Tokens) + Passlib (bcrypt)
• AI/Forensics: Transformers (SigLIP), Pillow, OpenCV (cv2)

---

⚙️ Environment Variables

Copy the .env.example file to .env in the backend/ directory to configure the application.

# Backend Environment Settings
PROJECT_NAME="AI Shield"
VERSION="1.0.0"
API_V1_STR="/api/v1"
CORS_ORIGINS=["http://localhost:5173", "http://127.0.0.1:5173"]

# Security
SECRET_KEY="your-super-secret-key-for-jwt-signing"
ACCESS_TOKEN_EXPIRE_MINUTES=1440

# Database
DATABASE_URL="sqlite+aiosqlite:///./aishield.db"

# AI Inference & Behavior
DEMO_MODE=True
MODEL_NAME="prithivMLmods/deepfake-detector-model-v1"

---

📸 Screenshots & UI

(Insert your hackathon presentation screenshots here)

• Dashboard: Real-time analytics, quota usage, and risk distribution.
• Analysis View: Live WebSocket processing with ELA and Grad-CAM visualization tabs.
• PDF Reports: Forensic reports generated dynamically upon job completion.

---

🎮 Demo Guide (Hackathon Walkthrough)

To present AI Shield flawlessly during a demo:

1. Login: Use the seeded demo account [email protected] (pw: demo).
2. Dashboard: Show the aggregated analytics and quota systems.
3. Upload: Drag-and-drop a sample test image (e.g., from tests/samples/) into the upload zone.
4. Live Processing: Watch the WebSocket stream update the 8-stage progress tracker in real-time.
5. Visual Inspection: Click the ELA tab to show structural manipulations, and the Grad-CAM tab to show the AI's heatmap focus.
6. Report Generation: Click "Download PDF Report" to export a professional forensic summary.
7. History: View the historical verification logs in the Data Table.

---

🔮 Future Scope

• Multi-Model Ensembles: Integrating Vision Transformers (ViT) alongside traditional CNNs.
• Video Forensics: Extending frame-by-frame extraction for deepfake video detection.
• Audio Verification: Integrating spectrogram analysis for AI-generated voice cloning.
• Enterprise SSO: SAML/OAuth2 integrations for corporate environments.

---

📚 Complete Technical Documentation

Explore the /docs directory for deep technical specifications:

1. Architecture Overview
2. API Reference & Endpoints
3. Database Schema & Migrations
4. AI Pipeline & Forensics
5. Upload & Result Processing Flow
6. WebSocket Real-Time Protocol
7. Final Project Evaluation Report

---

👥 Authors

Built by the AI Shield Team for digital forensics, media integrity verification, and ethical AI research.

🔒 License & Ethics

AI Shield is released under the MIT License.

Current AI Model Limitations

Important Notice: The AI Shield platform integrates the prithivMLmods/deepfake-detector-model-v1 (SigLIP) model hosted on Hugging Face for demonstration and architectural validation purposes.

• No Custom Fine-tuning: The detector leverages a dedicated Vision-Language model trained on deepfake representations or manipulated media datasets.
• Architecture Readiness: The platform is fully production-ready and architected to accept alternative Hugging Face weights in the future without structural changes.
• Performance Claims: The platform architecture safely supports dynamic loading of models. Current predictions should not be interpreted as validated forensic conclusions in mission-critical environments.