# ducbao210/video_deepfake_detection architecture

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

- Interactive diagram: https://gitdiagram.com/ducbao210/video_deepfake_detection
- Repository: https://github.com/ducbao210/video_deepfake_detection

## Overview

This is a video deepfake detection system spanning dataset preparation, model training and evaluation, and interactive inference. The main workflow prepares videos as sampled frames and actor-disjoint splits, trains frame-sequence classifiers, evaluates checkpoints, and serves predictions through a FastAPI backend with a Gradio interface. The graph preserves the documented model families, knowledge distillation, EDA, and Hugging Face checkpoint support. Some pipeline links are documented in the README rather than shown in sampled source; those relationships cite the README.

Main entry points: [`src/data/dataset.py`](https://github.com/ducbao210/video_deepfake_detection/blob/main/src/data/dataset.py) (Frame dataset), [`src/training/trainer.py`](https://github.com/ducbao210/video_deepfake_detection/blob/main/src/training/trainer.py) (Standard training), [`backend/dependencies.py`](https://github.com/ducbao210/video_deepfake_detection/blob/main/backend/dependencies.py) (Model loading and cache), [`src/training/kd_trainer.py`](https://github.com/ducbao210/video_deepfake_detection/blob/main/src/training/kd_trainer.py) (Distillation training)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_prep["Data preparation"]
  node_download["Dataset acquisition"]
  node_eda["Dataset analysis<br/>[01_eda.ipynb]"]
  node_frame_extract["Frame extraction<br/>[extract_frames.py]"]
  node_split["Actor-disjoint splits<br/>[split_dataset.py]"]
  node_dataset["Frame dataset<br/>[dataset.py]"]
  node_transforms["Image transforms<br/>[transforms.py]"]
end

subgraph group_learn["Model development"]
  node_architectures["Model architectures"]
  node_training["Standard training<br/>[trainer.py]"]
  node_kd["Distillation training<br/>[kd_trainer.py]"]
  node_engine["Training and evaluation engine<br/>[engine.py]"]
  node_optimizer["Optimizer and scheduler<br/>[optim.py]"]
  node_evaluation["Model evaluation<br/>[evaluate.py]"]
  node_checkpoints["Model checkpoints"]
end

subgraph group_serve["Inference services"]
  node_api["FastAPI service<br/>[main.py]"]
  node_model_manager["Model loading and cache<br/>[dependencies.py]"]
  node_inference["Video inference<br/>[inference.py]"]
  node_frontend["Gradio interface<br/>[app.py]"]
end

subgraph group_ops["Shared capabilities"]
  node_configs["Pipeline configuration<br/>[config.yaml]"]
  node_metrics["Metrics and plots<br/>[metrics.py]"]
end

node_dataset_source(("Video dataset"))
node_hub[("Hugging Face Hub")]
node_user(("User"))

node_dataset_source -->|"provides videos"| node_download
node_download -->|"supplies raw videos"| node_frame_extract
node_download -->|"feeds analysis"| node_eda
node_frame_extract -->|"precedes splitting"| node_split
node_split -->|"defines data splits"| node_dataset
node_dataset -->|"applies transforms"| node_transforms
node_configs -.->|"configures sampling"| node_dataset
node_configs -->|"configures preprocessing"| node_transforms
node_dataset -->|"supplies training data"| node_training
node_dataset -->|"supplies evaluation data"| node_evaluation
node_training -->|"runs epochs"| node_engine
node_training -->|"uses optimization"| node_optimizer
node_kd -->|"runs distillation steps"| node_engine
node_kd -->|"uses optimization"| node_optimizer
node_architectures -->|"provides classifiers"| node_training
node_training -->|"saves weights"| node_checkpoints
node_kd -->|"saves weights"| node_checkpoints
node_checkpoints -->|"uploads or downloads"| node_hub
node_hub -->|"provides checkpoints"| node_evaluation
node_evaluation -->|"computes metrics"| node_metrics
node_user -->|"submits video"| node_frontend
node_frontend -->|"requests prediction"| node_api
node_api -->|"loads model bundle"| node_model_manager
node_model_manager -->|"builds model"| node_architectures
node_model_manager -->|"loads settings"| node_configs
node_api -->|"extracts video frames"| node_inference
node_model_manager -.->|"fetches missing weights"| node_hub
node_inference -->|"runs prediction"| node_architectures
node_inference -->|"preprocesses frames"| node_transforms

click node_download "https://github.com/ducbao210/video_deepfake_detection/blob/main/scripts/download_dataset.py"
click node_eda "https://github.com/ducbao210/video_deepfake_detection/blob/main/notebooks/01_eda.ipynb"
click node_frame_extract "https://github.com/ducbao210/video_deepfake_detection/blob/main/scripts/extract_frames.py"
click node_split "https://github.com/ducbao210/video_deepfake_detection/blob/main/scripts/split_dataset.py"
click node_dataset "https://github.com/ducbao210/video_deepfake_detection/blob/main/src/data/dataset.py"
click node_transforms "https://github.com/ducbao210/video_deepfake_detection/blob/main/src/data/transforms.py"
click node_configs "https://github.com/ducbao210/video_deepfake_detection/blob/main/configs/config.yaml"
click node_architectures "https://github.com/ducbao210/video_deepfake_detection/tree/main/src/models"
click node_training "https://github.com/ducbao210/video_deepfake_detection/blob/main/src/training/trainer.py"
click node_kd "https://github.com/ducbao210/video_deepfake_detection/blob/main/src/training/kd_trainer.py"
click node_engine "https://github.com/ducbao210/video_deepfake_detection/blob/main/src/training/engine.py"
click node_optimizer "https://github.com/ducbao210/video_deepfake_detection/blob/main/src/training/optim.py"
click node_evaluation "https://github.com/ducbao210/video_deepfake_detection/blob/main/scripts/evaluate.py"
click node_api "https://github.com/ducbao210/video_deepfake_detection/blob/main/backend/main.py"
click node_model_manager "https://github.com/ducbao210/video_deepfake_detection/blob/main/backend/dependencies.py"
click node_inference "https://github.com/ducbao210/video_deepfake_detection/blob/main/scripts/inference.py"
click node_frontend "https://github.com/ducbao210/video_deepfake_detection/blob/main/frontend/app.py"
click node_metrics "https://github.com/ducbao210/video_deepfake_detection/blob/main/src/utils/metrics.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_download,node_eda,node_frame_extract,node_split,node_dataset,node_transforms,node_user toneBlue
class node_architectures,node_training,node_kd,node_engine,node_optimizer,node_evaluation,node_checkpoints,node_hub toneAmber
class node_api,node_model_manager,node_inference,node_frontend toneMint
class node_configs,node_metrics toneRose
class node_dataset_source toneIndigo
```

## Components

### Data preparation

- [Dataset acquisition](https://github.com/ducbao210/video_deepfake_detection/blob/main/scripts/download_dataset.py): `scripts/download_dataset.py`
- [Dataset analysis](https://github.com/ducbao210/video_deepfake_detection/blob/main/notebooks/01_eda.ipynb): `notebooks/01_eda.ipynb`
- [Frame extraction](https://github.com/ducbao210/video_deepfake_detection/blob/main/scripts/extract_frames.py): `scripts/extract_frames.py`
- [Actor-disjoint splits](https://github.com/ducbao210/video_deepfake_detection/blob/main/scripts/split_dataset.py): `scripts/split_dataset.py`
- [Frame dataset](https://github.com/ducbao210/video_deepfake_detection/blob/main/src/data/dataset.py): `src/data/dataset.py`
- [Image transforms](https://github.com/ducbao210/video_deepfake_detection/blob/main/src/data/transforms.py): `src/data/transforms.py`

### Model development

- [Model architectures](https://github.com/ducbao210/video_deepfake_detection/tree/main/src/models): `src/models`
- [Standard training](https://github.com/ducbao210/video_deepfake_detection/blob/main/src/training/trainer.py): `src/training/trainer.py`
- [Distillation training](https://github.com/ducbao210/video_deepfake_detection/blob/main/src/training/kd_trainer.py): `src/training/kd_trainer.py`
- [Training and evaluation engine](https://github.com/ducbao210/video_deepfake_detection/blob/main/src/training/engine.py): `src/training/engine.py`
- [Optimizer and scheduler](https://github.com/ducbao210/video_deepfake_detection/blob/main/src/training/optim.py): `src/training/optim.py`
- [Model evaluation](https://github.com/ducbao210/video_deepfake_detection/blob/main/scripts/evaluate.py): `scripts/evaluate.py`
- **Model checkpoints**

### Inference services

- [FastAPI service](https://github.com/ducbao210/video_deepfake_detection/blob/main/backend/main.py): `backend/main.py`
- [Model loading and cache](https://github.com/ducbao210/video_deepfake_detection/blob/main/backend/dependencies.py): `backend/dependencies.py`
- [Video inference](https://github.com/ducbao210/video_deepfake_detection/blob/main/scripts/inference.py): `scripts/inference.py`
- [Gradio interface](https://github.com/ducbao210/video_deepfake_detection/blob/main/frontend/app.py): `frontend/app.py`

### Shared capabilities

- [Pipeline configuration](https://github.com/ducbao210/video_deepfake_detection/blob/main/configs/config.yaml): `configs/config.yaml`
- [Metrics and plots](https://github.com/ducbao210/video_deepfake_detection/blob/main/src/utils/metrics.py): `src/utils/metrics.py`

### Other components

- **Video dataset**
- **Hugging Face Hub**
- **User**

## Connections

- Video dataset → Dataset acquisition: provides videos (evidence: `README.md`)
- Dataset acquisition → Frame extraction: supplies raw videos (evidence: `README.md`)
- Dataset acquisition → Dataset analysis: feeds analysis (evidence: `README.md`)
- Frame extraction → Actor-disjoint splits: precedes splitting (evidence: `README.md`)
- Actor-disjoint splits → Frame dataset: defines data splits (evidence: `README.md`)
- Frame dataset → Image transforms: applies transforms (evidence: `src/data/dataset.py`)
- Pipeline configuration → Frame dataset: configures sampling
- Pipeline configuration → Image transforms: configures preprocessing (evidence: `src/data/transforms.py`)
- Frame dataset → Standard training: supplies training data
- Frame dataset → Model evaluation: supplies evaluation data (evidence: `scripts/evaluate.py`)
- Standard training → Training and evaluation engine: runs epochs (evidence: `src/training/trainer.py`)
- Standard training → Optimizer and scheduler: uses optimization
- Distillation training → Training and evaluation engine: runs distillation steps (evidence: `src/training/kd_trainer.py`)
- Distillation training → Optimizer and scheduler: uses optimization (evidence: `scripts/train_kd.py`)
- Model architectures → Standard training: provides classifiers (evidence: `scripts/train.py`)
- Standard training → Model checkpoints: saves weights (evidence: `README.md`)
- Distillation training → Model checkpoints: saves weights (evidence: `README.md`)
- Model checkpoints → Hugging Face Hub: uploads or downloads (evidence: `README.md`)
- Hugging Face Hub → Model evaluation: provides checkpoints (evidence: `README.md`)
- Model evaluation → Metrics and plots: computes metrics (evidence: `scripts/evaluate.py`)
- User → Gradio interface: submits video (evidence: `README.md`)
- Gradio interface → FastAPI service: requests prediction (evidence: `README.md`)
- FastAPI service → Model loading and cache: loads model bundle (evidence: `backend/main.py`)
- Model loading and cache → Model architectures: builds model (evidence: `backend/dependencies.py`)
- Model loading and cache → Pipeline configuration: loads settings (evidence: `backend/dependencies.py`)
- FastAPI service → Video inference: extracts video frames (evidence: `backend/main.py`)
- Model loading and cache → Hugging Face Hub: fetches missing weights
- Video inference → Model architectures: runs prediction (evidence: `scripts/inference.py`)
- Video inference → Image transforms: preprocesses frames (evidence: `scripts/inference.py`)
