# sumukhl17-lgtm/deepfake-detector architecture

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

- Interactive diagram: https://gitdiagram.com/sumukhl17-lgtm/deepfake-detector
- Repository: https://github.com/sumukhl17-lgtm/deepfake-detector

## Overview

Deepfake Detector accepts an uploaded image, detects and crops a face, extracts spatial, frequency, and pixel-forensic signals, then fuses them into a REAL/FAKE prediction. The web API also produces two Grad-CAM visualizations and records prediction metadata; the browser presents the label, confidence, and heatmaps. Training and dataset-preparation scripts are excluded from this runtime map. Architecture links reflect the sampled source; README documentation is brief, so unsampled subsystem wiring is not inferred.

Main entry points: [`models/pipeline.py`](https://github.com/sumukhl17-lgtm/deepfake-detector/blob/master/models/pipeline.py) (Inference pipeline), [`backend/app.py`](https://github.com/sumukhl17-lgtm/deepfake-detector/blob/master/backend/app.py) (Flask API), [`frontend/static/js/main.js`](https://github.com/sumukhl17-lgtm/deepfake-detector/blob/master/frontend/static/js/main.js) (Upload and results UI), [`backend/database.py`](https://github.com/sumukhl17-lgtm/deepfake-detector/blob/master/backend/database.py) (Prediction audit writer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web interface"]
  node_browser["Upload and results UI<br/>[main.js]"]
  node_page["Analysis page<br/>[index.html]"]
  node_api["Flask API<br/>[app.py]"]
  node_uploads["Uploaded images and heatmaps<br/>[app.py]"]
end

subgraph group_inference["Detection inference"]
  node_pipeline["Inference pipeline<br/>[pipeline.py]"]
  node_face["Face detection and crop<br/>[pipeline.py]"]
  node_fusion["Feature fusion classifier<br/>[fusion.py]"]
end

subgraph group_signals["Signal analysis"]
  node_spatial["Spatial features<br/>[spatial.py]"]
  node_frequency["Frequency features<br/>[frequency.py]"]
  node_forensic["Pixel-forensic features<br/>[forensic.py]"]
end

subgraph group_explain["Explainability and audit"]
  node_gradcam["Spatial Grad-CAM<br/>[gradcam.py]"]
  node_forensiccam["Forensic Grad-CAM<br/>[gradcam.py]"]
  node_audit["Prediction audit writer<br/>[database.py]"]
  node_db[("Audit log<br/>[database.py]")]
end

node_user(("Image uploader"))

node_user -->|"selects image"| node_browser
node_browser -->|"uses page"| node_page
node_browser -->|"posts image"| node_api
node_api -->|"stores input and heatmaps"| node_uploads
node_api -->|"runs inference"| node_pipeline
node_pipeline -->|"detects and crops"| node_face
node_pipeline -->|"extracts features"| node_spatial
node_pipeline -->|"extracts features"| node_frequency
node_pipeline -->|"extracts features"| node_forensic
node_pipeline -->|"classifies features"| node_fusion
node_pipeline -->|"generates heatmap"| node_gradcam
node_pipeline -->|"generates heatmap"| node_forensiccam
node_api -->|"logs prediction"| node_audit
node_audit -->|"writes record"| node_db
node_api -->|"returns prediction and heatmap URLs"| node_browser
node_browser -->|"loads heatmaps"| node_uploads

click node_browser "https://github.com/sumukhl17-lgtm/deepfake-detector/blob/master/frontend/static/js/main.js"
click node_page "https://github.com/sumukhl17-lgtm/deepfake-detector/blob/master/frontend/templates/index.html"
click node_api "https://github.com/sumukhl17-lgtm/deepfake-detector/blob/master/backend/app.py"
click node_uploads "https://github.com/sumukhl17-lgtm/deepfake-detector/blob/master/backend/app.py"
click node_pipeline "https://github.com/sumukhl17-lgtm/deepfake-detector/blob/master/models/pipeline.py"
click node_face "https://github.com/sumukhl17-lgtm/deepfake-detector/blob/master/models/pipeline.py"
click node_spatial "https://github.com/sumukhl17-lgtm/deepfake-detector/blob/master/models/spatial.py"
click node_frequency "https://github.com/sumukhl17-lgtm/deepfake-detector/blob/master/models/frequency.py"
click node_forensic "https://github.com/sumukhl17-lgtm/deepfake-detector/blob/master/models/forensic.py"
click node_fusion "https://github.com/sumukhl17-lgtm/deepfake-detector/blob/master/models/fusion.py"
click node_gradcam "https://github.com/sumukhl17-lgtm/deepfake-detector/blob/master/explainability/gradcam.py"
click node_forensiccam "https://github.com/sumukhl17-lgtm/deepfake-detector/blob/master/explainability/gradcam.py"
click node_audit "https://github.com/sumukhl17-lgtm/deepfake-detector/blob/master/backend/database.py"
click node_db "https://github.com/sumukhl17-lgtm/deepfake-detector/blob/master/backend/database.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_browser,node_page,node_api,node_uploads toneBlue
class node_pipeline,node_face,node_fusion toneAmber
class node_spatial,node_frequency,node_forensic toneMint
class node_gradcam,node_forensiccam,node_audit,node_db toneRose
class node_user toneIndigo
```

## Components

### Web interface

- [Upload and results UI](https://github.com/sumukhl17-lgtm/deepfake-detector/blob/master/frontend/static/js/main.js): `frontend/static/js/main.js`
- [Analysis page](https://github.com/sumukhl17-lgtm/deepfake-detector/blob/master/frontend/templates/index.html): `frontend/templates/index.html`
- [Flask API](https://github.com/sumukhl17-lgtm/deepfake-detector/blob/master/backend/app.py): `backend/app.py`
- [Uploaded images and heatmaps](https://github.com/sumukhl17-lgtm/deepfake-detector/blob/master/backend/app.py): `backend/app.py`

### Detection inference

- [Inference pipeline](https://github.com/sumukhl17-lgtm/deepfake-detector/blob/master/models/pipeline.py): `models/pipeline.py`
- [Face detection and crop](https://github.com/sumukhl17-lgtm/deepfake-detector/blob/master/models/pipeline.py): `models/pipeline.py`
- [Feature fusion classifier](https://github.com/sumukhl17-lgtm/deepfake-detector/blob/master/models/fusion.py): `models/fusion.py`

### Signal analysis

- [Spatial features](https://github.com/sumukhl17-lgtm/deepfake-detector/blob/master/models/spatial.py): `models/spatial.py`
- [Frequency features](https://github.com/sumukhl17-lgtm/deepfake-detector/blob/master/models/frequency.py): `models/frequency.py`
- [Pixel-forensic features](https://github.com/sumukhl17-lgtm/deepfake-detector/blob/master/models/forensic.py): `models/forensic.py`

### Explainability and audit

- [Spatial Grad-CAM](https://github.com/sumukhl17-lgtm/deepfake-detector/blob/master/explainability/gradcam.py): `explainability/gradcam.py`
- [Forensic Grad-CAM](https://github.com/sumukhl17-lgtm/deepfake-detector/blob/master/explainability/gradcam.py): `explainability/gradcam.py`
- [Prediction audit writer](https://github.com/sumukhl17-lgtm/deepfake-detector/blob/master/backend/database.py): `backend/database.py`
- [Audit log](https://github.com/sumukhl17-lgtm/deepfake-detector/blob/master/backend/database.py): `backend/database.py`

### Other components

- **Image uploader**

## Connections

- Image uploader → Upload and results UI: selects image
- Upload and results UI → Analysis page: uses page
- Upload and results UI → Flask API: posts image
- Flask API → Uploaded images and heatmaps: stores input and heatmaps
- Flask API → Inference pipeline: runs inference
- Inference pipeline → Face detection and crop: detects and crops
- Inference pipeline → Spatial features: extracts features
- Inference pipeline → Frequency features: extracts features
- Inference pipeline → Pixel-forensic features: extracts features
- Inference pipeline → Feature fusion classifier: classifies features
- Inference pipeline → Spatial Grad-CAM: generates heatmap
- Inference pipeline → Forensic Grad-CAM: generates heatmap
- Flask API → Prediction audit writer: logs prediction
- Prediction audit writer → Audit log: writes record
- Flask API → Upload and results UI: returns prediction and heatmap URLs
- Upload and results UI → Uploaded images and heatmaps: loads heatmaps