# nguyentrongnguyen04/deepfake-detection architecture

> Architecture diagram of the GitHub repository nguyentrongnguyen04/deepfake-detection, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nguyentrongnguyen04/deepfake-detection
- Repository: https://github.com/nguyentrongnguyen04/deepfake-detection

## Overview

##### Project type and purpose
- DeepGuard is primarily a single-page front-end application that integrates with an external AI/ML service (Gradio API hosting Xception deepfake models).
- Its purpose is to let end users upload images, select a detection model, submit to the AI back end for analysis, and display deepfake probability, confidence scores, and history.

##### File structure
- Top-level “project” directory contains:
- public/ — static assets (favicon, index.html shell)
- src/ — the entire React application
– components/ — reusable UI components (Header, Footer, ImageUploader, ResultsDisplay, etc.)
– sections/ — page sections (Hero, Detection, About, HowItWorks)
– contexts/ — React Context for theming
– utils/ — helper functions (mock detector, localStorage wrapper, API client)
– types/ — shared TypeScript interfaces
– App.tsx, main.tsx — application bootstrap
- Configuration files: vite.config.ts, tsconfig.json, tailwind.config.js, eslint.config.js

##### README for additional insights
- Confirms front-end tech stack, Gradio API integration, and feature set (model selection, image upload, history tracking, dark mode).

a. Main components
- User’s Web Browser
- Front-end Application
– UI Layer: React components, Tailwind CSS, Framer Motion
– State & Context: ThemeContext, component state for model, image, results
– Utility Layer: API client (utils/api.ts), storage helper (utils/storage.ts)
- External AI Service
– Gradio API endpoint wrapping the Xception model
- Local Persistence
– browser localStorage (analysis history)

b. Relationships and interactions
1. User interacts with UI components (ModelSelector, ImageUploader)
2. On submit, front-end sends HTTP request via API client to Gradio API
3. Gradio API processes the image using Xception and returns JSON results
4. Front-end receives results, updates state, renders ResultsDisplay and MetricsDisplay
5. Front-end writes record to localStorage (history) and displays via HistoryPanel

c. Architectural patterns and design principles
- Component-based UI with clear separation of concerns
- Context API for cross-cutting concerns (theme)
- Utility modules for side effects (network calls, storage)
- Single source of truth in top-level App component

d. Key technologies
- React + TypeScript for type-safe UI
- Vite for development/build
- Tailwind CSS for styling, Framer Motion for animation
- Gradio API (external) for deep learning inference
- localStorage for client-side persistence

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User
    Browser["User Web Browser"]

    %% Front-end Application
    subgraph "Front-end Application"
        direction TB

        subgraph "UI Layer"
            direction TB
            Header["Header"]:::frontend
            Footer["Footer"]:::frontend
            HeroSection["Hero Section"]:::frontend
            DetectionSection["Detection Section"]:::frontend
            AboutSection["About Section"]:::frontend
            HowItWorksSection["How It Works Section"]:::frontend
            ImageUploader["Image Uploader"]:::frontend
            ModelSelector["Model Selector"]:::frontend
            ResultsDisplay["Results Display"]:::frontend
            MetricsDisplay["Metrics Display"]:::frontend
            HistoryPanel["History Panel"]:::frontend
            ProcessingAnimation["Processing Animation"]:::frontend
            ThemeToggle["Theme Toggle"]:::frontend
            BackgroundParticles["Background Particles"]:::frontend
            HeroParticles["Hero Particles"]:::frontend
        end

        subgraph "State & Context"
            direction TB
            AppBootstrap["App.tsx (Single Source of Truth)"]:::frontend
            EntryPoint["main.tsx (Application Entry Point)"]:::frontend
            ThemeContext["ThemeContext"]:::frontend
        end

        subgraph "Utilities"
            direction TB
            APIClient["API Client (utils/api.ts)"]:::frontend
            StorageHelper["Local Storage Helper (utils/storage.ts)"]:::frontend
            MockDetector["Mock Detector (utils/mock-detector.ts)"]:::frontend
        end
    end

    %% External AI Service
    GradioAPI["Gradio AI Service (Xception Model)"]:::external

    %% Local Persistence
    LocalStorage[(localStorage)]:::storage

    %% Relationships
    Browser -->|"interacts with"| Header
    Browser -->|interacts with| ModelSelector
    Browser -->|interacts with| ImageUploader
    ImageUploader -->|provides image| APIClient
    ModelSelector -->|selects model| APIClient
    APIClient -->|"POST /predict"| GradioAPI
    GradioAPI -->|"returns JSON results"| APIClient
    APIClient -->|updates state| ResultsDisplay
    ResultsDisplay -->|renders metrics| MetricsDisplay
    ResultsDisplay -->|stores record| StorageHelper
    StorageHelper -->|GET/SET localStorage| LocalStorage
    HistoryPanel -->|reads history| StorageHelper
    AppBootstrap -->|initializes| ThemeContext
    EntryPoint -->|boots| AppBootstrap

    %% Click Events
    click Header "https://github.com/nguyentrongnguyen04/deepfake-detection/blob/main/project/src/components/Header.tsx"
    click Footer "https://github.com/nguyentrongnguyen04/deepfake-detection/blob/main/project/src/components/Footer.tsx"
    click HeroSection "https://github.com/nguyentrongnguyen04/deepfake-detection/blob/main/project/src/sections/Hero.tsx"
    click DetectionSection "https://github.com/nguyentrongnguyen04/deepfake-detection/blob/main/project/src/sections/Detection.tsx"
    click AboutSection "https://github.com/nguyentrongnguyen04/deepfake-detection/blob/main/project/src/components/AboutDeepfakes.tsx"
    click HowItWorksSection "https://github.com/nguyentrongnguyen04/deepfake-detection/blob/main/project/src/components/HowItWorks.tsx"
    click ImageUploader "https://github.com/nguyentrongnguyen04/deepfake-detection/blob/main/project/src/components/ImageUploader.tsx"
    click ModelSelector "https://github.com/nguyentrongnguyen04/deepfake-detection/blob/main/project/src/components/ModelSelector.tsx"
    click ResultsDisplay "https://github.com/nguyentrongnguyen04/deepfake-detection/blob/main/project/src/components/ResultsDisplay.tsx"
    click MetricsDisplay "https://github.com/nguyentrongnguyen04/deepfake-detection/blob/main/project/src/components/MetricsDisplay.tsx"
    click HistoryPanel "https://github.com/nguyentrongnguyen04/deepfake-detection/blob/main/project/src/components/HistoryPanel.tsx"
    click ProcessingAnimation "https://github.com/nguyentrongnguyen04/deepfake-detection/blob/main/project/src/components/ProcessingAnimation.tsx"
    click ThemeToggle "https://github.com/nguyentrongnguyen04/deepfake-detection/blob/main/project/src/components/ThemeToggle.tsx"
    click BackgroundParticles "https://github.com/nguyentrongnguyen04/deepfake-detection/blob/main/project/src/components/BackgroundParticles.tsx"
    click HeroParticles "https://github.com/nguyentrongnguyen04/deepfake-detection/blob/main/project/src/components/HeroParticles.tsx"
    click ThemeContext "https://github.com/nguyentrongnguyen04/deepfake-detection/blob/main/project/src/contexts/ThemeContext.tsx"
    click StorageHelper "https://github.com/nguyentrongnguyen04/deepfake-detection/blob/main/project/src/utils/storage.ts"
    click MockDetector "https://github.com/nguyentrongnguyen04/deepfake-detection/blob/main/project/src/utils/mock-detector.ts"
    click AppBootstrap "https://github.com/nguyentrongnguyen04/deepfake-detection/blob/main/project/src/App.tsx"
    click EntryPoint "https://github.com/nguyentrongnguyen04/deepfake-detection/blob/main/project/src/main.tsx"

    %% Styles
    classDef frontend fill:#cfe2ff,stroke:#6fa8dc,stroke-width:1px
    classDef external fill:#ffe6cc,stroke:#f6b26b,stroke-width:1px
    classDef storage fill:#d9ead3,stroke:#93c47d,stroke-width:1px
```
