# srirammayan/deepfake-detection architecture

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

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

## Overview

#### Purpose and Entry Points
This repository implements deepfake detection using Vision Transformer (ViT) and CLIP-style vision-language model components. It also intends to make detection records immutable through blockchain and distribute results through SMTP, though the available tree does not expose dedicated blockchain or email integration modules.

Primary execution and validation entry points are:
- `main.py`
- `validate.py`

#### Runtime Configuration
`config.py` is the central likely source of model, dataset, and runtime parameters consumed by the execution pipeline. Python is the primary runtime, with dependencies declared in:
- `requirements.txt`
- `config.py`

#### Detection Pipeline
The main flow is expected to accept image/video-derived visual input, preprocess it into model-ready tensors, execute deepfake classification, and report a result.

Core stages are represented by:
- Input transformation: `preprocess.py`
- Main orchestration: `main.py`
- Evaluation/inference validation: `validate.py`

The boundary between raw media handling and learned inference is `preprocess.py`, which should produce normalized inputs compatible with the vision models.

#### Vision Transformer Backbone
The repository contains a local ViT implementation rather than relying solely on an external model package. The backbone and its supporting mechanisms are separated into:
- Transformer model definition: `vision_transformer.py`
- Shared transformer utilities: `vision_transformer_utils.py`
- Supporting model pieces: `vision_transformer_misc.py`

This layer is the primary learned visual-feature extraction boundary. It converts preprocessed image patches into contextual token or embedding representations used by detection logic.

#### CLIP Model Layer
CLIP-related modules provide an additional multimodal or pretrained embedding path:
- CLIP interface/loading logic: `clip.py`
- CLIP model definitions: `clip_models.py`

These files form a distinct model boundary from the native ViT implementation. `main.py` can select or combine these representations for deepfake classification, while preprocessing must satisfy each model’s expected image format.

#### Region-Aware Analysis
`region_awareness.py` indicates a specialized stage that focuses inference on image regions rather than treating every image uniformly. It likely consumes visual embeddings or feature maps from the ViT/CLIP layers and produces region-sensitive signals that improve detection of localized GAN artifacts.

Relevant paths:
- `region_awareness.py`
- `vision_transformer.py`
- `clip_models.py`

#### Result Handling and External-Service Intent
The README specifies two post-detection concerns: immutable blockchain records and SMTP result delivery. No explicit service adapters, smart-contract code, credentials modules, or mail clients appear in the tree. Therefore, these integrations are either incomplete, embedded in orchestration code, or expected to be supplied externally.

The likely control boundary is:
- Model result generation in `main.py`
- Result checking/reporting in `validate.py`

Any production integration should keep blockchain persistence and SMTP delivery outside the model modules so inference remains usable without external network dependencies.

Main entry points: [`main.py`](https://github.com/srirammayan/deepfake-detection/blob/main/main.py) (Main Orchestrator), [`vision_transformer.py`](https://github.com/srirammayan/deepfake-detection/blob/main/vision_transformer.py) (Local ViT Backbone), [`preprocess.py`](https://github.com/srirammayan/deepfake-detection/blob/main/preprocess.py) (Media Preprocessing), [`region_awareness.py`](https://github.com/srirammayan/deepfake-detection/blob/main/region_awareness.py) (Region-Aware Analysis)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_requirements["Dependencies<br/>dependency manifest<br/>[requirements.txt]"]
  node_config["Runtime Config<br/>configuration<br/>[config.py]"]
end

subgraph group_models["Vision Models"]
  node_vit["Local ViT Backbone<br/>transformer model"]
  node_vit_utils["ViT Utilities<br/>transformer support"]
  node_vit_misc["ViT Components<br/>model support"]
  node_clip["CLIP Loader<br/>model interface<br/>[clip.py]"]
  node_clip_models["CLIP Models<br/>model definitions<br/>[clip_models.py]"]
end

subgraph group_pipeline["Detection Pipeline"]
  node_main["Main Orchestrator<br/>Python entry point<br/>[main.py]"]
  node_validate["Validation<br/>Python entry point<br/>[validate.py]"]
  node_preprocess["Media Preprocessing<br/>input transformation<br/>[preprocess.py]"]
  node_region["Region-Aware Analysis<br/>artifact analysis"]
  node_result["Detection Result<br/>classification output"]
end

subgraph group_external["External-Service Intent"]
  node_blockchain[("Blockchain Record<br/>external persistence")]
  node_smtp["SMTP Delivery<br/>external notification"]
end

node_requirements -->|"provides dependencies"| node_main
node_config -->|"configures"| node_main
node_config -->|"configures"| node_validate
node_main -->|"prepares input"| node_preprocess
node_preprocess -->|"normalized tensors"| node_vit
node_preprocess -->|"model-ready images"| node_clip
node_vit_utils -->|"supports"| node_vit
node_vit_misc -->|"supports"| node_vit
node_clip -->|"loads"| node_clip_models
node_vit -->|"visual features"| node_region
node_clip_models -->|"visual embeddings"| node_region
node_region -->|"region-sensitive signal"| node_result
node_main -->|"classifies and reports"| node_result
node_result -->|"checked by"| node_validate
node_result -.->|"intended persistence"| node_blockchain
node_result -.->|"intended delivery"| node_smtp

click node_requirements "https://github.com/srirammayan/deepfake-detection/blob/main/requirements.txt"
click node_config "https://github.com/srirammayan/deepfake-detection/blob/main/config.py"
click node_main "https://github.com/srirammayan/deepfake-detection/blob/main/main.py"
click node_validate "https://github.com/srirammayan/deepfake-detection/blob/main/validate.py"
click node_preprocess "https://github.com/srirammayan/deepfake-detection/blob/main/preprocess.py"
click node_vit "https://github.com/srirammayan/deepfake-detection/blob/main/vision_transformer.py"
click node_vit_utils "https://github.com/srirammayan/deepfake-detection/blob/main/vision_transformer_utils.py"
click node_vit_misc "https://github.com/srirammayan/deepfake-detection/blob/main/vision_transformer_misc.py"
click node_clip "https://github.com/srirammayan/deepfake-detection/blob/main/clip.py"
click node_clip_models "https://github.com/srirammayan/deepfake-detection/blob/main/clip_models.py"
click node_region "https://github.com/srirammayan/deepfake-detection/blob/main/region_awareness.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_requirements,node_config toneBlue
class node_vit,node_vit_utils,node_vit_misc,node_clip,node_clip_models toneAmber
class node_main,node_validate,node_preprocess,node_region,node_result toneMint
class node_blockchain,node_smtp toneRose
```

## Components

### Runtime

- [Dependencies](https://github.com/srirammayan/deepfake-detection/blob/main/requirements.txt): dependency manifest · `requirements.txt`
- [Runtime Config](https://github.com/srirammayan/deepfake-detection/blob/main/config.py): configuration · Model, dataset, and runtime parameters. · `config.py`

### Vision Models

- [Local ViT Backbone](https://github.com/srirammayan/deepfake-detection/blob/main/vision_transformer.py): transformer model · Extracts contextual visual token or embedding features. · `vision_transformer.py`
- [ViT Utilities](https://github.com/srirammayan/deepfake-detection/blob/main/vision_transformer_utils.py): transformer support · `vision_transformer_utils.py`
- [ViT Components](https://github.com/srirammayan/deepfake-detection/blob/main/vision_transformer_misc.py): model support · `vision_transformer_misc.py`
- [CLIP Loader](https://github.com/srirammayan/deepfake-detection/blob/main/clip.py): model interface · Loads or exposes the CLIP-style vision-language path. · `clip.py`
- [CLIP Models](https://github.com/srirammayan/deepfake-detection/blob/main/clip_models.py): model definitions · `clip_models.py`

### Detection Pipeline

- [Main Orchestrator](https://github.com/srirammayan/deepfake-detection/blob/main/main.py): Python entry point · Runs preprocessing, model inference, and result generation. · `main.py`
- [Validation](https://github.com/srirammayan/deepfake-detection/blob/main/validate.py): Python entry point · Checks or reports inference results. · `validate.py`
- [Media Preprocessing](https://github.com/srirammayan/deepfake-detection/blob/main/preprocess.py): input transformation · Converts visual input into normalized model tensors. · `preprocess.py`
- [Region-Aware Analysis](https://github.com/srirammayan/deepfake-detection/blob/main/region_awareness.py): artifact analysis · Produces localized signals for deepfake artifacts. · `region_awareness.py`
- **Detection Result**: classification output

### External-Service Intent

No dedicated integration modules are exposed.

- **Blockchain Record**: external persistence · Intended immutable result persistence; adapter is not exposed.
- **SMTP Delivery**: external notification · Intended result delivery; mail client is not exposed.

## Connections

- Dependencies → Main Orchestrator: provides dependencies
- Runtime Config → Main Orchestrator: configures
- Runtime Config → Validation: configures
- Main Orchestrator → Media Preprocessing: prepares input
- Media Preprocessing → Local ViT Backbone: normalized tensors
- Media Preprocessing → CLIP Loader: model-ready images
- ViT Utilities → Local ViT Backbone: supports
- ViT Components → Local ViT Backbone: supports
- CLIP Loader → CLIP Models: loads
- Local ViT Backbone → Region-Aware Analysis: visual features
- CLIP Models → Region-Aware Analysis: visual embeddings
- Region-Aware Analysis → Detection Result: region-sensitive signal
- Main Orchestrator → Detection Result: classifies and reports
- Detection Result → Validation: checked by
- Detection Result → Blockchain Record: intended persistence
- Detection Result → SMTP Delivery: intended delivery