# dessa-oss/deepfake-detection architecture

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

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

## Overview

##### Project Type and Main Purpose
- The project is a research / experimental deep learning system focused on deepfake detection.
- It leverages PyTorch (with a pretrained ResNet18) which is finetuned for detecting image/video manipulations.
- The system utilizes a combination of data ingestion (from FaceForensics++ and augmented YouTube datasets), preprocessing, training, and hyperparameter search (with the hparams_search.py script).
- Docker is used to containerize and run experiments consistently on machines with GPU support (nvidia-docker integration) and the Atlas scheduler.

##### Key Components
a. Data Ingestion and Preprocessing:
- Data Download: Scripts like faceforensics_download.py and download_T.sh for pulling data.
- Data Restructuring: The restructure_data.sh script prepares datasets into the required structure, as detailed in the README.
- Data Loader: The data_loader.py script (and potentially portions of utils.py) functions to load and preprocess data for training.

b. Training and Experimentation:
- Model Definition: The model is defined in model.py and possibly used in train.py.
- Training and Experiment Scripts:
- main.py and train.py are used to run training/inference experiments.
- hparams_search.py is responsible for running large-scale experiments and hyperparameter search.

c. Docker Containerization:
- Custom Docker Image: The custom_docker_image directory contents (Dockerfile, requirements.txt) show that a dedicated docker image (built with nvidia-docker) is used. Include this container as an “Execution Environment” block.
- job.config.yaml: This file configures the job parameters, including the docker image tag and paths to the datasets.
- That updating job.config.yaml is needed if Docker image names or paths change.

d. External and Supporting Tools/Dependencies:
- Atlas Experiment Manager: Integration for scheduling and managing experiments.
- External Tools: Dependencies like NVIDIA-Docker and ffmpeg.
- Pre-trained Models: The pretrained ResNet18 (mention that it comes from ImageNet) that serves as the starting point for finetuning.
- Reference to external datasets: Links to FaceForensics++ and YouTube/S3 datasets.

##### Relationships and Interactions
- That once training is scheduled (using hparams_search.py following configuration in job.config.yaml), experiments run inside the Docker container built from the custom_docker_image.
- Experiment manager (Atlas) to the training execution environment, highlighting integration.

##### Architectural Patterns and Design Principles
- Modular Design: Demonstrate separation between data handling, model training, and experiment management.
- Experiment Configuration: Show the importance of configuration files (job.config.yaml) to link deployment (the docker image) and data paths.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Ingestion & Preprocessing Layer
    subgraph "Data Ingestion & Preprocessing"
        ffd["faceforensics_download.py"]:::data
        dt["download_T.sh"]:::data
        rds["restructure_data.sh"]:::data
        dl["data_loader.py"]:::data
        data["Datasets((Datasets))"]:::data
        ffd -->|"runs"| rds
        dt -->|"runs"| rds
        rds -->|"prepares"| dl
        dl -->|"loads"| data
    end

    %% Training & Experimentation Layer
    subgraph "Training & Experimentation"
        md["Model Definition (model.py)"]:::training
        pr["Pretrained ResNet18 (ImageNet)"]:::training
        mp["Training Inference: main.py"]:::training
        tp["Training Inference: train.py"]:::training
        hp["Hyperparameter Search (hparams_search.py)"]:::training
        data -->|"input"| md
        pr -->|"initializes"| md
        md -->|"triggers"| mp
        md -->|"triggers"| tp
        mp -->|"optimizes"| hp
        tp -->|"optimizes"| hp
    end

    %% Infrastructure & Execution Environment Layer
    subgraph "Infrastructure & Execution Environment"
        docker["Docker Containerization & Execution Environment"]:::infrastructure
        job["Experiment Config (job.config.yaml)"]:::infrastructure
        atlas["Atlas Experiment Manager"]:::infrastructure
        ext["External Tools (NVIDIA-docker, ffmpeg)"]:::infrastructure
        job -->|"configures"| docker
        atlas -->|"schedules"| docker
        ext -->|"supports"| docker
        hp -->|"executes via"| docker
        docker -->|"runs"| mp
        docker -->|"runs"| tp
    end

    %% Click Events
    click ffd "https://github.com/dessa-oss/deepfake-detection/blob/master/faceforensics_download.py"
    click dt "https://github.com/dessa-oss/deepfake-detection/blob/master/download_T.sh"
    click rds "https://github.com/dessa-oss/deepfake-detection/blob/master/restructure_data.sh"
    click dl "https://github.com/dessa-oss/deepfake-detection/blob/master/data_loader.py"
    click md "https://github.com/dessa-oss/deepfake-detection/blob/master/model.py"
    click mp "https://github.com/dessa-oss/deepfake-detection/blob/master/main.py"
    click tp "https://github.com/dessa-oss/deepfake-detection/blob/master/train.py"
    click hp "https://github.com/dessa-oss/deepfake-detection/blob/master/hparams_search.py"
    click docker "https://github.com/dessa-oss/deepfake-detection/tree/master/custom_docker_image"
    click job "https://github.com/dessa-oss/deepfake-detection/blob/master/job.config.yaml"

    %% Styles
    classDef data fill:#a8e6cf,stroke:#333,stroke-width:2px;
    classDef training fill:#ffe4b5,stroke:#333,stroke-width:2px;
    classDef infrastructure fill:#add8e6e,stroke:#333,stroke-width:2px;
```
