# hanmoonsub/deepguard architecture

> Architecture diagram of the GitHub repository hanmoonsub/deepguard, 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/hanmoonsub/deepguard
- Repository: https://github.com/hanmoonsub/deepguard

## Overview

DeepGuard combines a browser application and FastAPI/Celery services for authenticated image and video deepfake analysis, plus a reusable model, data-preparation, training, and explainability stack. The documented workflow uploads media, queues inference, stores results, and presents probabilities and video details; separate XAI views expose model-focus heatmaps. The sampled routes and services support the upload-to-worker-to-result path. Some model, explainability, and preprocessing wiring is documented rather than shown in the excerpts, so those links are kept conservative.

Main entry points: [`App/routes/inference.py`](https://github.com/hanmoonsub/deepguard/blob/main/App/routes/inference.py) (Inference routes), [`App/celery_app.py`](https://github.com/hanmoonsub/deepguard/blob/main/App/celery_app.py) (Celery worker), [`client/src/App.js`](https://github.com/hanmoonsub/deepguard/blob/main/client/src/App.js) (React app), [`deepguard/models/ms_eff_gcvit.py`](https://github.com/hanmoonsub/deepguard/blob/main/deepguard/models/ms_eff_gcvit.py) (DeepGuard models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_frontend["React app<br/>[App.js]"]
  node_analysis_pages["Analysis pages<br/>[analysispage.js]"]
  node_result_pages["Results and heatmaps"]
end

subgraph group_api["API and jobs"]
  node_api_app["FastAPI app<br/>[main.py]"]
  node_auth_routes["Auth routes<br/>[auth.py]"]
  node_inference_routes["Inference routes<br/>[inference.py]"]
  node_auth_service["Auth service<br/>[auth_svc.py]"]
  node_image_service["Image service<br/>[image_svc.py]"]
  node_video_service["Video service<br/>[video_svc.py]"]
  node_inference_service["Inference coordinator<br/>[inference_svc.py]"]
  node_worker["Celery worker<br/>[celery_app.py]"]
end

subgraph group_ml["Detection stack"]
  node_image_predictor["Image predictor"]
  node_video_predictor["Video predictor"]
  node_model["DeepGuard models<br/>[ms_eff_gcvit.py]"]
  node_explainability["XAI explainers<br/>[cam_explainer.py]"]
end

subgraph group_research["Model development"]
  node_preprocess["Face and frame prep<br/>[face_detector.py]"]
  node_datasets["Training datasets<br/>[dataset.py]"]
  node_training["Training scripts<br/>[train_eff_gcvit.py]"]
end

node_user(("User"))
node_database[("MySQL")]
node_redis[("Redis")]

node_user -->|"uses"| node_frontend
node_frontend -->|"API requests"| node_api_app
node_frontend -->|"routes to"| node_analysis_pages
node_frontend -->|"routes to"| node_result_pages
node_api_app -->|"dispatches"| node_auth_routes
node_api_app -->|"dispatches"| node_inference_routes
node_auth_routes -->|"calls"| node_auth_service
node_auth_routes -->|"reads/writes"| node_database
node_inference_routes -->|"uploads and records"| node_image_service
node_inference_routes -->|"uploads and records"| node_video_service
node_inference_routes -->|"queues tasks"| node_inference_service
node_inference_routes -->|"reads results"| node_database
node_inference_service -->|"registers tasks"| node_worker
node_inference_service -->|"dispatches tasks"| node_redis
node_worker -->|"runs image inference"| node_image_predictor
node_worker -->|"runs video inference"| node_video_predictor
node_worker -->|"updates image results"| node_image_service
node_worker -->|"updates video results"| node_video_service
node_image_service -->|"reads/writes"| node_database
node_video_service -->|"reads/writes"| node_database
node_image_predictor -->|"predicts with"| node_model
node_video_predictor -->|"predicts with"| node_model
node_explainability -.->|"explains"| node_model
node_preprocess -.->|"prepares data for"| node_datasets
node_datasets -.->|"supplies data"| node_training
node_training -->|"trains"| node_model

click node_frontend "https://github.com/hanmoonsub/deepguard/blob/main/client/src/App.js"
click node_analysis_pages "https://github.com/hanmoonsub/deepguard/blob/main/client/src/pages/analysispage.js"
click node_result_pages "https://github.com/hanmoonsub/deepguard/blob/main/client/src/pages/AnalysisDetailPage.js"
click node_api_app "https://github.com/hanmoonsub/deepguard/blob/main/App/main.py"
click node_auth_routes "https://github.com/hanmoonsub/deepguard/blob/main/App/routes/auth.py"
click node_inference_routes "https://github.com/hanmoonsub/deepguard/blob/main/App/routes/inference.py"
click node_auth_service "https://github.com/hanmoonsub/deepguard/blob/main/App/services/auth_svc.py"
click node_image_service "https://github.com/hanmoonsub/deepguard/blob/main/App/services/image_svc.py"
click node_video_service "https://github.com/hanmoonsub/deepguard/blob/main/App/services/video_svc.py"
click node_inference_service "https://github.com/hanmoonsub/deepguard/blob/main/App/services/inference_svc.py"
click node_worker "https://github.com/hanmoonsub/deepguard/blob/main/App/celery_app.py"
click node_image_predictor "https://github.com/hanmoonsub/deepguard/blob/main/inference/image_predictor_prt.py"
click node_video_predictor "https://github.com/hanmoonsub/deepguard/blob/main/inference/video_predictor_prt.py"
click node_model "https://github.com/hanmoonsub/deepguard/blob/main/deepguard/models/ms_eff_gcvit.py"
click node_explainability "https://github.com/hanmoonsub/deepguard/blob/main/explainability/explainer/cam_explainer.py"
click node_preprocess "https://github.com/hanmoonsub/deepguard/blob/main/preprocess/face_detector.py"
click node_datasets "https://github.com/hanmoonsub/deepguard/blob/main/deepguard/data/dataset.py"
click node_training "https://github.com/hanmoonsub/deepguard/blob/main/train_eff_gcvit.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_frontend,node_analysis_pages,node_result_pages,node_user toneBlue
class node_api_app,node_auth_routes,node_inference_routes,node_auth_service,node_image_service,node_video_service,node_inference_service,node_worker,node_database,node_redis toneAmber
class node_image_predictor,node_video_predictor,node_model,node_explainability toneMint
class node_preprocess,node_datasets,node_training toneRose
```

## Components

### Web experience

- [React app](https://github.com/hanmoonsub/deepguard/blob/main/client/src/App.js): `client/src/App.js`
- [Analysis pages](https://github.com/hanmoonsub/deepguard/blob/main/client/src/pages/analysispage.js): `client/src/pages/analysispage.js`
- [Results and heatmaps](https://github.com/hanmoonsub/deepguard/blob/main/client/src/pages/AnalysisDetailPage.js): `client/src/pages/AnalysisDetailPage.js`

### API and jobs

- [FastAPI app](https://github.com/hanmoonsub/deepguard/blob/main/App/main.py): `App/main.py`
- [Auth routes](https://github.com/hanmoonsub/deepguard/blob/main/App/routes/auth.py): `App/routes/auth.py`
- [Inference routes](https://github.com/hanmoonsub/deepguard/blob/main/App/routes/inference.py): `App/routes/inference.py`
- [Auth service](https://github.com/hanmoonsub/deepguard/blob/main/App/services/auth_svc.py): `App/services/auth_svc.py`
- [Image service](https://github.com/hanmoonsub/deepguard/blob/main/App/services/image_svc.py): `App/services/image_svc.py`
- [Video service](https://github.com/hanmoonsub/deepguard/blob/main/App/services/video_svc.py): `App/services/video_svc.py`
- [Inference coordinator](https://github.com/hanmoonsub/deepguard/blob/main/App/services/inference_svc.py): `App/services/inference_svc.py`
- [Celery worker](https://github.com/hanmoonsub/deepguard/blob/main/App/celery_app.py): `App/celery_app.py`

### Detection stack

- [Image predictor](https://github.com/hanmoonsub/deepguard/blob/main/inference/image_predictor_prt.py): `inference/image_predictor_prt.py`
- [Video predictor](https://github.com/hanmoonsub/deepguard/blob/main/inference/video_predictor_prt.py): `inference/video_predictor_prt.py`
- [DeepGuard models](https://github.com/hanmoonsub/deepguard/blob/main/deepguard/models/ms_eff_gcvit.py): `deepguard/models/ms_eff_gcvit.py`
- [XAI explainers](https://github.com/hanmoonsub/deepguard/blob/main/explainability/explainer/cam_explainer.py): `explainability/explainer/cam_explainer.py`

### Model development

- [Face and frame prep](https://github.com/hanmoonsub/deepguard/blob/main/preprocess/face_detector.py): `preprocess/face_detector.py`
- [Training datasets](https://github.com/hanmoonsub/deepguard/blob/main/deepguard/data/dataset.py): `deepguard/data/dataset.py`
- [Training scripts](https://github.com/hanmoonsub/deepguard/blob/main/train_eff_gcvit.py): `train_eff_gcvit.py`

### Other components

- **User**
- **MySQL**
- **Redis**

## Connections

- User → React app: uses
- React app → FastAPI app: API requests
- React app → Analysis pages: routes to
- React app → Results and heatmaps: routes to
- FastAPI app → Auth routes: dispatches
- FastAPI app → Inference routes: dispatches
- Auth routes → Auth service: calls
- Auth routes → MySQL: reads/writes
- Inference routes → Image service: uploads and records
- Inference routes → Video service: uploads and records
- Inference routes → Inference coordinator: queues tasks
- Inference routes → MySQL: reads results
- Inference coordinator → Celery worker: registers tasks
- Inference coordinator → Redis: dispatches tasks
- Celery worker → Image predictor: runs image inference
- Celery worker → Video predictor: runs video inference
- Celery worker → Image service: updates image results
- Celery worker → Video service: updates video results
- Image service → MySQL: reads/writes
- Video service → MySQL: reads/writes
- Image predictor → DeepGuard models: predicts with
- Video predictor → DeepGuard models: predicts with
- XAI explainers → DeepGuard models: explains
- Face and frame prep → Training datasets: prepares data for
- Training datasets → Training scripts: supplies data
- Training scripts → DeepGuard models: trains