# baranidharan16/sih-email-forensics-full architecture

> Architecture diagram of the GitHub repository baranidharan16/sih-email-forensics-full, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/baranidharan16/sih-email-forensics-full
- Repository: https://github.com/baranidharan16/sih-email-forensics-full

## Overview

MailShield is an email-forensics and threat-response platform. Analysts upload email artifacts through the web workspace; backend analysis parses and scores them, enriches findings with intelligence, and stores investigation evidence. A follow-on advanced pipeline can sandbox suspicious artifacts and produce SOC-oriented results, while the UI exposes cases, alerts, AI assistance, and integrity records. The README documents these capabilities; source excerpts and the SOURCE INDEX substantiate several internal calls. Other unsampled route and integration details are represented only at supported subsystem level.

Main entry points: [`backend/app/services/investigation_service.py`](https://github.com/baranidharan16/sih-email-forensics-full/blob/main/backend/app/services/investigation_service.py) (Investigation Service), [`backend/main.py`](https://github.com/baranidharan16/sih-email-forensics-full/blob/main/backend/main.py) (FastAPI Application), [`backend/app/advanced/pipeline.py`](https://github.com/baranidharan16/sih-email-forensics-full/blob/main/backend/app/advanced/pipeline.py) (Advanced Pipeline), [`frontend/src/App.tsx`](https://github.com/baranidharan16/sih-email-forensics-full/blob/main/frontend/src/App.tsx) (MailShield UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Analyst Workspace"]
  node_web["MailShield UI<br/>[App.tsx]"]
  node_http_client["API Client<br/>[client.ts]"]
end

subgraph group_api["API and Identity"]
  node_backend["FastAPI Application<br/>[main.py]"]
  node_auth["Auth Routes<br/>[auth.py]"]
  node_auth_deps["Session Authorization<br/>[auth_deps.py]"]
  node_analysis_routes["Analysis Routes<br/>[analysis.py]"]
  node_investigation_api["Investigation API<br/>[investigations.py]"]
end

subgraph group_analysis["Forensic Analysis"]
  node_investigation_service["Investigation Service"]
  node_forensic_engine["Forensic Engine<br/>[engine.py]"]
  node_ml_features["ML Features<br/>[features.py]"]
  node_ml_models["ML Model Provider<br/>[model_provider.py]"]
  node_ai_fusion["AI Fusion<br/>[fusion.py]"]
end

subgraph group_response["Threat Response"]
  node_forensic_ai["Forensic AI<br/>[engine.py]"]
  node_intel["Threat Intelligence"]
  node_advanced_pipeline["Advanced Pipeline<br/>[pipeline.py]"]
  node_sandbox_client["Sandbox Client<br/>[client.py]"]
  node_sandbox_engine["Artifact Sandbox<br/>[engine.py]"]
  node_advanced_domains["SOC, GRC, VAPT"]
end

subgraph group_persistence["Evidence and Storage"]
  node_ledger["Integrity Ledger<br/>[ledger.py]"]
  node_investigation_models["Investigation Records<br/>[investigation.py]"]
  node_database[("Relational Database<br/>[session.py]")]
end

node_analyst(("SOC Analyst"))

node_analyst -->|"uses"| node_web
node_web -.->|"requests data"| node_http_client
node_http_client -->|"calls API"| node_backend
node_backend -->|"mounts routes"| node_analysis_routes
node_backend -->|"mounts routes"| node_investigation_api
node_backend -->|"mounts routes"| node_auth
node_analysis_routes -.->|"starts analysis"| node_forensic_engine
node_investigation_api -.->|"delegates to"| node_investigation_service
node_investigation_service -->|"runs analysis"| node_forensic_engine
node_investigation_service -->|"extracts features"| node_ml_features
node_investigation_service -->|"uses models"| node_ml_models
node_investigation_service -->|"fuses findings"| node_ai_fusion
node_ai_fusion -->|"uses findings"| node_forensic_engine
node_ai_fusion -->|"uses models"| node_ml_models
node_investigation_service -->|"enriches findings"| node_intel
node_investigation_service -->|"anchors evidence"| node_ledger
node_investigation_service -->|"persists records"| node_investigation_models
node_database -->|"maps models"| node_investigation_models
node_auth -->|"uses authorization"| node_auth_deps
node_auth_deps -->|"loads sessions"| node_database
node_investigation_service -.->|"continues response"| node_advanced_pipeline
node_advanced_pipeline -->|"requests sandboxing"| node_sandbox_client
node_sandbox_client -.->|"submits artifacts"| node_sandbox_engine
node_advanced_pipeline -->|"runs assessments"| node_advanced_domains
node_advanced_pipeline -->|"anchors report"| node_ledger
node_web -.->|"offers investigation chat"| node_forensic_ai

click node_web "https://github.com/baranidharan16/sih-email-forensics-full/blob/main/frontend/src/App.tsx"
click node_http_client "https://github.com/baranidharan16/sih-email-forensics-full/blob/main/frontend/src/api/client.ts"
click node_backend "https://github.com/baranidharan16/sih-email-forensics-full/blob/main/backend/main.py"
click node_auth "https://github.com/baranidharan16/sih-email-forensics-full/blob/main/backend/routes/auth.py"
click node_auth_deps "https://github.com/baranidharan16/sih-email-forensics-full/blob/main/backend/utils/auth_deps.py"
click node_analysis_routes "https://github.com/baranidharan16/sih-email-forensics-full/blob/main/backend/routes/analysis.py"
click node_investigation_api "https://github.com/baranidharan16/sih-email-forensics-full/blob/main/backend/app/api/v1/investigations.py"
click node_investigation_service "https://github.com/baranidharan16/sih-email-forensics-full/blob/main/backend/app/services/investigation_service.py"
click node_forensic_engine "https://github.com/baranidharan16/sih-email-forensics-full/blob/main/backend/app/forensic/engine.py"
click node_ml_features "https://github.com/baranidharan16/sih-email-forensics-full/blob/main/backend/app/ml/features.py"
click node_ml_models "https://github.com/baranidharan16/sih-email-forensics-full/blob/main/backend/app/ml/model_provider.py"
click node_ai_fusion "https://github.com/baranidharan16/sih-email-forensics-full/blob/main/backend/app/ai/fusion.py"
click node_forensic_ai "https://github.com/baranidharan16/sih-email-forensics-full/blob/main/backend/app/forensic_ai/engine.py"
click node_intel "https://github.com/baranidharan16/sih-email-forensics-full/tree/main/backend/app/intel"
click node_advanced_pipeline "https://github.com/baranidharan16/sih-email-forensics-full/blob/main/backend/app/advanced/pipeline.py"
click node_sandbox_client "https://github.com/baranidharan16/sih-email-forensics-full/blob/main/backend/app/sandbox/client.py"
click node_sandbox_engine "https://github.com/baranidharan16/sih-email-forensics-full/blob/main/sandbox/sandbox_app/engine.py"
click node_advanced_domains "https://github.com/baranidharan16/sih-email-forensics-full/tree/main/backend/app/advanced"
click node_ledger "https://github.com/baranidharan16/sih-email-forensics-full/blob/main/backend/app/blockchain/ledger.py"
click node_investigation_models "https://github.com/baranidharan16/sih-email-forensics-full/blob/main/backend/app/models/investigation.py"
click node_database "https://github.com/baranidharan16/sih-email-forensics-full/blob/main/backend/app/database/session.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_web,node_http_client toneBlue
class node_backend,node_auth,node_auth_deps,node_analysis_routes,node_investigation_api toneAmber
class node_investigation_service,node_forensic_engine,node_ml_features,node_ml_models,node_ai_fusion toneMint
class node_forensic_ai,node_intel,node_advanced_pipeline,node_sandbox_client,node_sandbox_engine,node_advanced_domains toneRose
class node_ledger,node_investigation_models,node_database,node_analyst toneIndigo
```

## Components

### Analyst Workspace

- [MailShield UI](https://github.com/baranidharan16/sih-email-forensics-full/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [API Client](https://github.com/baranidharan16/sih-email-forensics-full/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`

### API and Identity

- [FastAPI Application](https://github.com/baranidharan16/sih-email-forensics-full/blob/main/backend/main.py): `backend/main.py`
- [Auth Routes](https://github.com/baranidharan16/sih-email-forensics-full/blob/main/backend/routes/auth.py): `backend/routes/auth.py`
- [Session Authorization](https://github.com/baranidharan16/sih-email-forensics-full/blob/main/backend/utils/auth_deps.py): `backend/utils/auth_deps.py`
- [Analysis Routes](https://github.com/baranidharan16/sih-email-forensics-full/blob/main/backend/routes/analysis.py): `backend/routes/analysis.py`
- [Investigation API](https://github.com/baranidharan16/sih-email-forensics-full/blob/main/backend/app/api/v1/investigations.py): `backend/app/api/v1/investigations.py`

### Forensic Analysis

- [Investigation Service](https://github.com/baranidharan16/sih-email-forensics-full/blob/main/backend/app/services/investigation_service.py): `backend/app/services/investigation_service.py`
- [Forensic Engine](https://github.com/baranidharan16/sih-email-forensics-full/blob/main/backend/app/forensic/engine.py): `backend/app/forensic/engine.py`
- [ML Features](https://github.com/baranidharan16/sih-email-forensics-full/blob/main/backend/app/ml/features.py): `backend/app/ml/features.py`
- [ML Model Provider](https://github.com/baranidharan16/sih-email-forensics-full/blob/main/backend/app/ml/model_provider.py): `backend/app/ml/model_provider.py`
- [AI Fusion](https://github.com/baranidharan16/sih-email-forensics-full/blob/main/backend/app/ai/fusion.py): `backend/app/ai/fusion.py`

### Threat Response

- [Forensic AI](https://github.com/baranidharan16/sih-email-forensics-full/blob/main/backend/app/forensic_ai/engine.py): `backend/app/forensic_ai/engine.py`
- [Threat Intelligence](https://github.com/baranidharan16/sih-email-forensics-full/tree/main/backend/app/intel): `backend/app/intel`
- [Advanced Pipeline](https://github.com/baranidharan16/sih-email-forensics-full/blob/main/backend/app/advanced/pipeline.py): `backend/app/advanced/pipeline.py`
- [Sandbox Client](https://github.com/baranidharan16/sih-email-forensics-full/blob/main/backend/app/sandbox/client.py): `backend/app/sandbox/client.py`
- [Artifact Sandbox](https://github.com/baranidharan16/sih-email-forensics-full/blob/main/sandbox/sandbox_app/engine.py): `sandbox/sandbox_app/engine.py`
- [SOC, GRC, VAPT](https://github.com/baranidharan16/sih-email-forensics-full/tree/main/backend/app/advanced): `backend/app/advanced`

### Evidence and Storage

- [Integrity Ledger](https://github.com/baranidharan16/sih-email-forensics-full/blob/main/backend/app/blockchain/ledger.py): `backend/app/blockchain/ledger.py`
- [Investigation Records](https://github.com/baranidharan16/sih-email-forensics-full/blob/main/backend/app/models/investigation.py): `backend/app/models/investigation.py`
- [Relational Database](https://github.com/baranidharan16/sih-email-forensics-full/blob/main/backend/app/database/session.py): `backend/app/database/session.py`

### Other components

- **SOC Analyst**

## Connections

- SOC Analyst → MailShield UI: uses (evidence: `README.md`)
- MailShield UI → API Client: requests data
- API Client → FastAPI Application: calls API (evidence: `frontend/src/api/client.ts`)
- FastAPI Application → Analysis Routes: mounts routes (evidence: `backend/main.py`)
- FastAPI Application → Investigation API: mounts routes (evidence: `backend/main.py`)
- FastAPI Application → Auth Routes: mounts routes (evidence: `backend/main.py`)
- Analysis Routes → Forensic Engine: starts analysis
- Investigation API → Investigation Service: delegates to
- Investigation Service → Forensic Engine: runs analysis (evidence: `backend/app/services/investigation_service.py`)
- Investigation Service → ML Features: extracts features (evidence: `backend/app/services/investigation_service.py`)
- Investigation Service → ML Model Provider: uses models (evidence: `backend/app/services/investigation_service.py`)
- Investigation Service → AI Fusion: fuses findings (evidence: `backend/app/services/investigation_service.py`)
- AI Fusion → Forensic Engine: uses findings (evidence: `backend/app/ai/fusion.py`)
- AI Fusion → ML Model Provider: uses models (evidence: `backend/app/ai/fusion.py`)
- Investigation Service → Threat Intelligence: enriches findings (evidence: `backend/app/services/investigation_service.py`)
- Investigation Service → Integrity Ledger: anchors evidence (evidence: `backend/app/services/investigation_service.py`)
- Investigation Service → Investigation Records: persists records (evidence: `backend/app/services/investigation_service.py`)
- Relational Database → Investigation Records: maps models (evidence: `backend/app/database/session.py`)
- Auth Routes → Session Authorization: uses authorization (evidence: `backend/routes/auth.py`)
- Session Authorization → Relational Database: loads sessions (evidence: `backend/utils/auth_deps.py`)
- Investigation Service → Advanced Pipeline: continues response (evidence: `backend/app/services/investigation_service.py`)
- Advanced Pipeline → Sandbox Client: requests sandboxing (evidence: `backend/app/advanced/pipeline.py`)
- Sandbox Client → Artifact Sandbox: submits artifacts
- Advanced Pipeline → SOC, GRC, VAPT: runs assessments (evidence: `backend/app/advanced/pipeline.py`)
- Advanced Pipeline → Integrity Ledger: anchors report (evidence: `backend/app/advanced/pipeline.py`)
- MailShield UI → Forensic AI: offers investigation chat
