# saarthaktiwari-04710/deepfake-detection architecture

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

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

## Overview

This repository combines a two-stream deepfake classifier, a training workflow, and a FastAPI inference/localization path. Training loads labeled images, prepares spatial and FFT inputs, optimizes the model, and evaluates AUC/EER. The inference router accepts uploads, runs face-aware classification, optionally requests localization for confident fake predictions, and formats a response. The separately defined main.py endpoint is a placeholder and is not shown as invoking that router. The README describes the two-stream design; the graph follows sampled implementation for wiring.

Main entry points: [`train.py`](https://github.com/saarthaktiwari-04710/deepfake-detection/blob/main/train.py) (Training loop), [`backend/app/routers/predict.py`](https://github.com/saarthaktiwari-04710/deepfake-detection/blob/main/backend/app/routers/predict.py) (Prediction router), [`backend/app/routers/backend/app/services/detector.py`](https://github.com/saarthaktiwari-04710/deepfake-detection/blob/main/backend/app/routers/backend/app/services/detector.py) (Detection service), [`backend/app/services/localizer.py`](https://github.com/saarthaktiwari-04710/deepfake-detection/blob/main/backend/app/services/localizer.py) (Localization service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_training["Model training"]
  node_trainer["Training loop<br/>[train.py]"]
  node_dataset["Image dataset<br/>[dataset.py]"]
  node_model["Two-stream model<br/>[models.py]"]
  node_metrics["Loss and metrics<br/>[utils.py]"]
  node_config["Training config<br/>[train_config.yaml]"]
end

subgraph group_inference["Inference services"]
  node_detector["Detection service<br/>[detector.py]"]
  node_face_detector["YOLO face detector"]
end

subgraph group_api["HTTP interfaces"]
  node_predict_router["Prediction router<br/>[predict.py]"]
  node_response_schema["Prediction response<br/>[schemas.py]"]
  node_placeholder_api["Placeholder endpoint<br/>[main.py]"]
end

subgraph group_explainability["Localization"]
  node_localizer["Localization service<br/>[localizer.py]"]
  node_sam["SAM segmentation"]
  node_gradcam["Grad-CAM"]
end

node_upload_user(("Image uploader"))
node_client(("API client"))

node_trainer -->|"reads config"| node_config
node_trainer -->|"creates datasets"| node_dataset
node_dataset -->|"yields image batches"| node_trainer
node_trainer -->|"trains and evaluates"| node_model
node_trainer -->|"computes loss and EER"| node_metrics
node_trainer -->|"saves weights"| node_model
node_upload_user -->|"uploads image"| node_predict_router
node_predict_router -->|"requests prediction"| node_detector
node_detector -->|"detects face"| node_face_detector
node_detector -->|"runs classifier"| node_model
node_detector -->|"returns verdict"| node_predict_router
node_predict_router -->|"requests mask"| node_localizer
node_localizer -->|"finds hotspot"| node_gradcam
node_localizer -->|"segments hotspot"| node_sam
node_localizer -->|"returns mask"| node_predict_router
node_predict_router -->|"formats response"| node_response_schema
node_client -->|"posts image"| node_placeholder_api

click node_trainer "https://github.com/saarthaktiwari-04710/deepfake-detection/blob/main/train.py"
click node_dataset "https://github.com/saarthaktiwari-04710/deepfake-detection/blob/main/src/dataset.py"
click node_model "https://github.com/saarthaktiwari-04710/deepfake-detection/blob/main/src/models.py"
click node_metrics "https://github.com/saarthaktiwari-04710/deepfake-detection/blob/main/src/utils.py"
click node_config "https://github.com/saarthaktiwari-04710/deepfake-detection/blob/main/configs/train_config.yaml"
click node_predict_router "https://github.com/saarthaktiwari-04710/deepfake-detection/blob/main/backend/app/routers/predict.py"
click node_detector "https://github.com/saarthaktiwari-04710/deepfake-detection/blob/main/backend/app/routers/backend/app/services/detector.py"
click node_localizer "https://github.com/saarthaktiwari-04710/deepfake-detection/blob/main/backend/app/services/localizer.py"
click node_response_schema "https://github.com/saarthaktiwari-04710/deepfake-detection/blob/main/backend/app/schemas.py"
click node_placeholder_api "https://github.com/saarthaktiwari-04710/deepfake-detection/blob/main/backend/app/main.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_trainer,node_dataset,node_model,node_metrics,node_config,node_client toneBlue
class node_detector,node_face_detector toneAmber
class node_predict_router,node_response_schema,node_placeholder_api toneMint
class node_localizer,node_sam,node_gradcam toneRose
class node_upload_user toneIndigo
```

## Components

### Model training

- [Training loop](https://github.com/saarthaktiwari-04710/deepfake-detection/blob/main/train.py): `train.py`
- [Image dataset](https://github.com/saarthaktiwari-04710/deepfake-detection/blob/main/src/dataset.py): `src/dataset.py`
- [Two-stream model](https://github.com/saarthaktiwari-04710/deepfake-detection/blob/main/src/models.py): `src/models.py`
- [Loss and metrics](https://github.com/saarthaktiwari-04710/deepfake-detection/blob/main/src/utils.py): `src/utils.py`
- [Training config](https://github.com/saarthaktiwari-04710/deepfake-detection/blob/main/configs/train_config.yaml): `configs/train_config.yaml`

### Inference services

- [Detection service](https://github.com/saarthaktiwari-04710/deepfake-detection/blob/main/backend/app/routers/backend/app/services/detector.py): `backend/app/routers/backend/app/services/detector.py`
- **YOLO face detector**

### HTTP interfaces

- [Prediction router](https://github.com/saarthaktiwari-04710/deepfake-detection/blob/main/backend/app/routers/predict.py): `backend/app/routers/predict.py`
- [Prediction response](https://github.com/saarthaktiwari-04710/deepfake-detection/blob/main/backend/app/schemas.py): `backend/app/schemas.py`
- [Placeholder endpoint](https://github.com/saarthaktiwari-04710/deepfake-detection/blob/main/backend/app/main.py): `backend/app/main.py`

### Localization

- [Localization service](https://github.com/saarthaktiwari-04710/deepfake-detection/blob/main/backend/app/services/localizer.py): `backend/app/services/localizer.py`
- **SAM segmentation**
- **Grad-CAM**

### Other components

- **Image uploader**
- **API client**

## Connections

- Training loop → Training config: reads config
- Training loop → Image dataset: creates datasets
- Image dataset → Training loop: yields image batches
- Training loop → Two-stream model: trains and evaluates
- Training loop → Loss and metrics: computes loss and EER
- Training loop → Two-stream model: saves weights
- Image uploader → Prediction router: uploads image
- Prediction router → Detection service: requests prediction
- Detection service → YOLO face detector: detects face
- Detection service → Two-stream model: runs classifier
- Detection service → Prediction router: returns verdict
- Prediction router → Localization service: requests mask
- Localization service → Grad-CAM: finds hotspot
- Localization service → SAM segmentation: segments hotspot
- Localization service → Prediction router: returns mask
- Prediction router → Prediction response: formats response
- API client → Placeholder endpoint: posts image