# srijansundaram/deepshield architecture

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

## Overview

DeepShield analyzes images and videos through a Streamlit interface or REST API, returning model verdicts and forensic evidence. The image path combines an ensemble detector with face analysis and advisory forensic signals; the video path adds frame-level, temporal, audio-visual, and identity checks. Results can be visualized, explained, logged, or exported as PDF. The README also documents URL analysis, batch scans, and Grad-CAM. Some wiring is supported only by the SOURCE INDEX or README; unsampled implementation details are not inferred.

Main entry points: [`app.py`](https://github.com/srijansundaram/deepshield/blob/main/app.py) (Streamlit App), [`api.py`](https://github.com/srijansundaram/deepshield/blob/main/api.py) (REST API), [`utils/video_utils.py`](https://github.com/srijansundaram/deepshield/blob/main/utils/video_utils.py) (Video Analysis), [`utils/face_utils.py`](https://github.com/srijansundaram/deepshield/blob/main/utils/face_utils.py) (Face Analysis)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User Interfaces"]
  node_streamlit_app["Streamlit App<br/>[app.py]"]
  node_rest_api["REST API<br/>[api.py]"]
end

subgraph group_analysis["Detection &amp; Forensics"]
  node_image_detector["Ensemble Detector<br/>[detector.py]"]
  node_face_analysis["Face Analysis<br/>[face_utils.py]"]
  node_forensics["Image Forensics<br/>[forensics.py]"]
  node_social_compression["Compression Handling"]
end

subgraph group_video["Video Analysis"]
  node_video_analysis["Video Analysis<br/>[video_utils.py]"]
  node_av_sync["Audio-Visual Sync<br/>[av_sync.py]"]
  node_identity["Identity Tracking"]
end

subgraph group_results["Results &amp; Reporting"]
  node_explainability["Signal Explainability<br/>[explainability.py]"]
  node_visualization["Charts &amp; Heatmaps<br/>[visualize.py]"]
  node_history["Session History<br/>[history.py]"]
  node_pdf_report["PDF Reports<br/>[pdf_report.py]"]
end

node_user(("User"))
node_api_client(("API Client"))
node_image_url["Public Image URL"]

node_user -->|"uses"| node_streamlit_app
node_api_client -->|"submits analysis"| node_rest_api
node_streamlit_app -->|"analyzes images"| node_image_detector
node_streamlit_app -->|"analyzes faces"| node_face_analysis
node_face_analysis -->|"predicts faces"| node_image_detector
node_streamlit_app -->|"computes signals"| node_forensics
node_streamlit_app -->|"adjusts artifacts"| node_social_compression
node_streamlit_app -->|"analyzes video"| node_video_analysis
node_video_analysis -->|"analyzes sync"| node_av_sync
node_video_analysis -->|"tracks identity"| node_identity
node_rest_api -->|"analyzes input"| node_image_detector
node_rest_api -->|"analyzes faces"| node_face_analysis
node_streamlit_app -->|"ranks signals"| node_explainability
node_streamlit_app -->|"renders charts"| node_visualization
node_streamlit_app -->|"records sessions"| node_history
node_streamlit_app -->|"exports reports"| node_pdf_report
node_image_url -.->|"provides image"| node_streamlit_app
node_streamlit_app -->|"returns results"| node_api_client

click node_streamlit_app "https://github.com/srijansundaram/deepshield/blob/main/app.py"
click node_rest_api "https://github.com/srijansundaram/deepshield/blob/main/api.py"
click node_image_detector "https://github.com/srijansundaram/deepshield/blob/main/models/detector.py"
click node_face_analysis "https://github.com/srijansundaram/deepshield/blob/main/utils/face_utils.py"
click node_forensics "https://github.com/srijansundaram/deepshield/blob/main/utils/forensics.py"
click node_social_compression "https://github.com/srijansundaram/deepshield/blob/main/utils/social_compression.py"
click node_video_analysis "https://github.com/srijansundaram/deepshield/blob/main/utils/video_utils.py"
click node_av_sync "https://github.com/srijansundaram/deepshield/blob/main/utils/av_sync.py"
click node_identity "https://github.com/srijansundaram/deepshield/blob/main/utils/identity_consistency.py"
click node_explainability "https://github.com/srijansundaram/deepshield/blob/main/utils/explainability.py"
click node_visualization "https://github.com/srijansundaram/deepshield/blob/main/utils/visualize.py"
click node_history "https://github.com/srijansundaram/deepshield/blob/main/utils/history.py"
click node_pdf_report "https://github.com/srijansundaram/deepshield/blob/main/reports/pdf_report.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_streamlit_app,node_rest_api,node_user,node_api_client toneBlue
class node_image_detector,node_face_analysis,node_forensics,node_social_compression toneAmber
class node_video_analysis,node_av_sync,node_identity toneMint
class node_explainability,node_visualization,node_history,node_pdf_report toneRose
class node_image_url toneIndigo
```

## Components

### User Interfaces

- [Streamlit App](https://github.com/srijansundaram/deepshield/blob/main/app.py): `app.py`
- [REST API](https://github.com/srijansundaram/deepshield/blob/main/api.py): `api.py`

### Detection & Forensics

- [Ensemble Detector](https://github.com/srijansundaram/deepshield/blob/main/models/detector.py): `models/detector.py`
- [Face Analysis](https://github.com/srijansundaram/deepshield/blob/main/utils/face_utils.py): `utils/face_utils.py`
- [Image Forensics](https://github.com/srijansundaram/deepshield/blob/main/utils/forensics.py): `utils/forensics.py`
- [Compression Handling](https://github.com/srijansundaram/deepshield/blob/main/utils/social_compression.py): `utils/social_compression.py`

### Video Analysis

- [Video Analysis](https://github.com/srijansundaram/deepshield/blob/main/utils/video_utils.py): `utils/video_utils.py`
- [Audio-Visual Sync](https://github.com/srijansundaram/deepshield/blob/main/utils/av_sync.py): `utils/av_sync.py`
- [Identity Tracking](https://github.com/srijansundaram/deepshield/blob/main/utils/identity_consistency.py): `utils/identity_consistency.py`

### Results & Reporting

- [Signal Explainability](https://github.com/srijansundaram/deepshield/blob/main/utils/explainability.py): `utils/explainability.py`
- [Charts & Heatmaps](https://github.com/srijansundaram/deepshield/blob/main/utils/visualize.py): `utils/visualize.py`
- [Session History](https://github.com/srijansundaram/deepshield/blob/main/utils/history.py): `utils/history.py`
- [PDF Reports](https://github.com/srijansundaram/deepshield/blob/main/reports/pdf_report.py): `reports/pdf_report.py`

### Other components

- **User**
- **API Client**
- **Public Image URL**

## Connections

- User → Streamlit App: uses (evidence: `README.md`)
- API Client → REST API: submits analysis (evidence: `README.md`)
- Streamlit App → Ensemble Detector: analyzes images (evidence: `app.py`)
- Streamlit App → Face Analysis: analyzes faces (evidence: `app.py`)
- Face Analysis → Ensemble Detector: predicts faces (evidence: `utils/face_utils.py`)
- Streamlit App → Image Forensics: computes signals (evidence: `app.py`)
- Streamlit App → Compression Handling: adjusts artifacts (evidence: `app.py`)
- Streamlit App → Video Analysis: analyzes video (evidence: `app.py`)
- Video Analysis → Audio-Visual Sync: analyzes sync (evidence: `utils/video_utils.py`)
- Video Analysis → Identity Tracking: tracks identity (evidence: `utils/video_utils.py`)
- REST API → Ensemble Detector: analyzes input (evidence: `api.py`)
- REST API → Face Analysis: analyzes faces (evidence: `api.py`)
- Streamlit App → Signal Explainability: ranks signals (evidence: `app.py`)
- Streamlit App → Charts & Heatmaps: renders charts (evidence: `app.py`)
- Streamlit App → Session History: records sessions (evidence: `app.py`)
- Streamlit App → PDF Reports: exports reports (evidence: `app.py`)
- Public Image URL → Streamlit App: provides image (evidence: `README.md`)
- Streamlit App → API Client: returns results (evidence: `README.md`)
