# siddharthksah/deepsafe architecture

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

- Interactive diagram: https://gitdiagram.com/siddharthksah/deepsafe
- Repository: https://github.com/siddharthksah/deepsafe

## Overview

##### Project Type & Purpose
- DeepSafe is a Streamlit-based web application dedicated to DeepFake detection. Its purpose is to offer a user-friendly interface so that users can upload images/videos or provide URLs to perform deepfake detection. The app supports multiple detection models (including custom ones) and benchmarking capabilities. The README and file structure indicate that the tool is designed to be modular and extensible, enabling both straightforward analysis and comparative benchmarking.

##### Analyzing the File Structure
- Top-Level Files & Directories:
- Files like main.py, README.md, Dockerfile, requirements.txt, and environment.yml indicate an application that can be easily containerized, deployed, and managed via standard Python dependency management.
- The “dashboard”, “leaderboard”, and “stats” directories indicate components for displaying results (e.g., charts, tables, CSV outputs) and benchmarking metrics of the deepfake detection models.
- The “assets” directory contains sample media (images/videos) and informative PDFs, suggesting resources for both testing and educational purposes.
- The “utils” directory contains several helper and processing functions (e.g., download utilities, temporary file management, data conversion) that support the main application.
- Architectural Hints:
- The presence of a “database” folder suggests that runtime or benchmarking data might be stored locally.
- “examples” provide sample usage scripts, making it clear the system is built around modular code that supports various input methods (file uploads, URL downloads).

##### Key Components
a. User Interface Layer:
- The Frontend is built using Streamlit. This component manages user inputs (file upload, URL input, model selection) and displays outputs (charts, tables, CSV downloads).
- Navigation components include selecting the “Detector”, “Examples”, and “Benchmarking” pages.

b. Core Detection Engine:
- The DeepFake detection engine supports multiple models (both pre-integrated and custom). The “Add_Custom_Model_to_DeepSafe.md” and several references in the README indicate that users can add or swap detection models.
- Depending on available hardware, users can choose to run inference on CPU or GPU (as indicated by the Processing Unit Selection).

c. Data & Benchmarking Management:
- The “dashboard”, “leaderboard”, and “stats” directories manage benchmarking results, visualizations, and statistical summaries.
- The local “database” folder logs user sessions or runtime data that could be used to compare and benchmark results.
- File management for uploaded or downloaded datasets is handled by utility functions in the “utils” directory.

d. External Components/Services:
- Integration with Google Drive for downloading model weights is clearly outlined in the README.
- The Dockerfile and configuration files indicate support for containerized deployments.

##### Relationships and Data Flows
- Users interact with the Streamlit UI (frontend) to submit data (images/videos or URLs).
- The UI passes the input to the Detection Engine where the selected DeepFake detection models perform analysis.
- Results (detection statistics, probability scores, inference times) are then stored in local databases, displayed in the “dashboard” and “stats”, and summarized within the “leaderboard”.
- Utility modules support this by managing tasks like downloading models, temporary file handling, and data transformation.
- The entire process benefits from containerized deployment (Dockerfile) and environment management (environment.yml, pyproject.toml).

##### Architectural Patterns & Technologies
- The project follows a modular monolithic design with clear layers: a presentation layer (Streamlit UI), a service layer (detection engine and benchmarking processing modules), and a data/storage layer (local database and file system storage).
- Key technologies include Python 3.8+, Streamlit for the interface, and various Python utilities for handling data.
- Docker is used for deployment, and external dependencies are managed via requirements.txt and environment.yml.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Presentation Layer"
        UI["Streamlit Web UI"]:::frontend
    end

    subgraph "Service Layer"
        DE["DeepFake Detection Engine"]:::engine
        PUDecision{"Processing Unit Selection (CPU/GPU)"}:::diamond
        US["Utility Services"]:::utility
    end

    subgraph "Data & Visualization Layer"
        DB["Local Database Storage"]:::data
        BV["Benchmarking & Visualization"]:::data
    end

    subgraph "Deployment & Environment"
        ED["External Deployment & Environment Management"]:::external
    end

    User(("User"))
    
    User -->|"interacts"| UI
    UI -->|"submits_data"| DE
    DE -->|"chooses_hardware"| PUDecision
    PUDecision -->|"performs_inference"| DE
    DE -->|"calls_helpers"| US
    DE -->|"stores_results"| DB
    DE -->|"updates_metrics"| BV
    US -->|"supports_tasks"| DE
    ED -->|"configures_UI"| UI
    ED -->|"configures_DE"| DE

    click UI "https://github.com/siddharthksah/deepsafe/blob/main/main.py"
    click UI "https://github.com/siddharthksah/deepsafe/blob/main/.streamlit/config.toml"

    click DE "https://github.com/siddharthksah/deepsafe/blob/main/main.py"
    click DE "https://github.com/siddharthksah/deepsafe/blob/main/Add_Custom_Model_to_DeepSafe.md"

    click BV "https://github.com/siddharthksah/deepsafe/blob/main/dashboard/plot_number_inferences.py"
    click BV "https://github.com/siddharthksah/deepsafe/tree/main/leaderboard/"
    click BV "https://github.com/siddharthksah/deepsafe/blob/main/stats/state.csv"
    click BV "https://github.com/siddharthksah/deepsafe/blob/main/stats/state.txt"

    click DB "https://github.com/siddharthksah/deepsafe/tree/main/database/"

    click US "https://github.com/siddharthksah/deepsafe/blob/main/utils/download_from_url.py"
    click US "https://github.com/siddharthksah/deepsafe/blob/main/utils/save_uploaded_image_temp.py"

    click ED "https://github.com/siddharthksah/deepsafe/tree/main/Dockerfile"
    click ED "https://github.com/siddharthksah/deepsafe/blob/main/environment.yml"
    click ED "https://github.com/siddharthksah/deepsafe/blob/main/requirements.txt"
    click ED "https://github.com/siddharthksah/deepsafe/blob/main/pyproject.toml"

    classDef frontend fill:#AED6F1,stroke:#3498DB,stroke-width:2px,color:#2C3E50;
    classDef engine fill:#F9E79F,stroke:#F4D03F,stroke-width:2px,color:#7D6608;
    classDef utility fill:#A9DFBF,stroke:#27AE60,stroke-width:2px,color:#145A32;
    classDef data fill:#F5CBA7,stroke:#E67E22,stroke-width:2px,color:#935116;
    classDef external fill:#D2B4DE,stroke:#8E44AD,stroke-width:2px,color:#4A235A;
    classDef diamond fill:#F1948A,stroke:#C0392B,stroke-width:2px,color:#641E16;
```
