# jashvanthan/sentineltrace architecture

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

- Interactive diagram: https://gitdiagram.com/jashvanthan/sentineltrace
- Repository: https://github.com/jashvanthan/sentineltrace

## Overview

SentinelTrace is a workspace-isolated email threat detection and digital forensics platform. Responders use the SOC workbench to authenticate, ingest suspicious email, review analysis and enrichment, investigate related campaigns or infrastructure, and produce evidence dossiers. The backend API and background worker coordinate analysis; persistence and graph services support investigation. The README documents these capabilities, while source excerpts and the SOURCE INDEX show selected implementation links. Some capability branches are documented but their internal call paths were not sampled, so those links are omitted or marked unverified.

Main entry points: [`backend/app/services/threat_service.py`](https://github.com/jashvanthan/sentineltrace/blob/master/backend/app/services/threat_service.py) (Threat orchestrator), [`backend/app/main.py`](https://github.com/jashvanthan/sentineltrace/blob/master/backend/app/main.py) (API application), [`mcp-server/src/server.py`](https://github.com/jashvanthan/sentineltrace/blob/master/mcp-server/src/server.py) (MCP tool bridge), [`backend/app/api/v1/emails.py`](https://github.com/jashvanthan/sentineltrace/blob/master/backend/app/api/v1/emails.py) (Email endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["SOC workbench"]
  node_webapp["Workbench UI"]
  node_emailui["Email review"]
  node_campaignui["Campaign graph"]
  node_geoui["Infrastructure map"]
end

subgraph group_api["API and access"]
  node_backend["API application<br/>[main.py]"]
  node_auth["Authentication<br/>[auth.py]"]
  node_emailapi["Email endpoints<br/>[emails.py]"]
  node_workspaces["Workspace access<br/>[workspaces.py]"]
  node_worker["Background worker<br/>[worker.py]"]
end

subgraph group_analysis["Email analysis"]
  node_analysisflow["Threat orchestrator<br/>[threat_service.py]"]
  node_emailparse["Email parsing<br/>[email_service.py]"]
  node_ai["AI classification<br/>[ai_service.py]"]
  node_agents["Analysis agents"]
  node_analysisdata[("Analysis records<br/>[email_analysis.py]")]
end

subgraph group_investigation["Investigation and evidence"]
  node_intel["Threat intelligence<br/>[intel_service.py]"]
  node_geo["Geolocation<br/>[geo_service.py]"]
  node_iptrace["IP trace<br/>[service.py]"]
  node_campaigns[("Campaign correlation<br/>[neo4j_service.py]")]
  node_reports["Forensic reports"]
end

subgraph group_integrations["External integrations"]
  node_gmail["Gmail integration<br/>[gmail_service.py]"]
  node_gcs[("Encrypted evidence storage<br/>[gcs_service.py]")]
  node_mcp["MCP tool bridge<br/>[server.py]"]
end

node_responder(("Responder"))
node_llmprovider(("LLM provider"))
node_threatfeeds(("Threat intelligence providers"))
node_postgres[("PostgreSQL")]

node_responder -->|"uses"| node_webapp
node_webapp -.->|"requests API"| node_backend
node_backend -->|"routes to"| node_auth
node_backend -->|"routes to"| node_emailapi
node_backend -->|"routes to"| node_workspaces
node_emailapi -->|"invokes"| node_analysisflow
node_emailapi -->|"queues analysis"| node_worker
node_worker -->|"runs"| node_analysisflow
node_analysisflow -->|"parses email"| node_emailparse
node_analysisflow -->|"classifies"| node_ai
node_analysisflow -->|"enriches indicators"| node_intel
node_analysisflow -->|"enriches IPs"| node_geo
node_analysisflow -->|"updates graph"| node_campaigns
node_analysisflow -->|"stores evidence"| node_gcs
node_analysisflow -.->|"records results"| node_analysisdata
node_emailui -.->|"reviews"| node_analysisdata
node_campaignui -.->|"explores"| node_campaigns
node_geoui -.->|"visualizes"| node_iptrace
node_analysisflow -.->|"traces infrastructure"| node_iptrace
node_analysisflow -.->|"generates dossiers"| node_reports
node_gmail -->|"supplies messages"| node_worker
node_threatfeeds -.->|"provides enrichment"| node_intel
node_ai -->|"requests analysis"| node_llmprovider
node_mcp -->|"exposes tools"| node_emailparse
node_mcp -->|"exposes tools"| node_intel
node_mcp -->|"exposes tools"| node_geo
node_auth -.->|"stores sessions"| node_postgres
node_analysisdata -.->|"persists in"| node_postgres

click node_webapp "https://github.com/jashvanthan/sentineltrace/tree/master/frontend/src"
click node_emailui "https://github.com/jashvanthan/sentineltrace/blob/master/frontend/src/pages/EmailAnalysisPage.tsx"
click node_campaignui "https://github.com/jashvanthan/sentineltrace/blob/master/frontend/src/pages/CampaignGraphPage.tsx"
click node_geoui "https://github.com/jashvanthan/sentineltrace/blob/master/frontend/src/pages/GeolocationPage.tsx"
click node_backend "https://github.com/jashvanthan/sentineltrace/blob/master/backend/app/main.py"
click node_auth "https://github.com/jashvanthan/sentineltrace/blob/master/backend/app/api/v1/auth.py"
click node_emailapi "https://github.com/jashvanthan/sentineltrace/blob/master/backend/app/api/v1/emails.py"
click node_workspaces "https://github.com/jashvanthan/sentineltrace/blob/master/backend/app/api/v1/workspaces.py"
click node_worker "https://github.com/jashvanthan/sentineltrace/blob/master/backend/app/worker.py"
click node_analysisflow "https://github.com/jashvanthan/sentineltrace/blob/master/backend/app/services/threat_service.py"
click node_emailparse "https://github.com/jashvanthan/sentineltrace/blob/master/backend/app/services/email_service.py"
click node_ai "https://github.com/jashvanthan/sentineltrace/blob/master/backend/app/services/ai_service.py"
click node_agents "https://github.com/jashvanthan/sentineltrace/tree/master/backend/app/agents"
click node_analysisdata "https://github.com/jashvanthan/sentineltrace/blob/master/backend/app/models/email_analysis.py"
click node_intel "https://github.com/jashvanthan/sentineltrace/blob/master/backend/app/services/intel_service.py"
click node_geo "https://github.com/jashvanthan/sentineltrace/blob/master/backend/app/services/geo_service.py"
click node_iptrace "https://github.com/jashvanthan/sentineltrace/blob/master/backend/app/services/ip_trace/service.py"
click node_campaigns "https://github.com/jashvanthan/sentineltrace/blob/master/backend/app/services/neo4j_service.py"
click node_reports "https://github.com/jashvanthan/sentineltrace/blob/master/backend/app/services/forensic_report_service.py"
click node_gmail "https://github.com/jashvanthan/sentineltrace/blob/master/backend/app/services/gmail_service.py"
click node_gcs "https://github.com/jashvanthan/sentineltrace/blob/master/backend/app/services/gcs_service.py"
click node_mcp "https://github.com/jashvanthan/sentineltrace/blob/master/mcp-server/src/server.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_webapp,node_emailui,node_campaignui,node_geoui toneBlue
class node_backend,node_auth,node_emailapi,node_workspaces,node_worker,node_postgres toneAmber
class node_analysisflow,node_emailparse,node_ai,node_agents,node_analysisdata toneMint
class node_intel,node_geo,node_iptrace,node_campaigns,node_reports toneRose
class node_gmail,node_gcs,node_mcp,node_responder,node_llmprovider,node_threatfeeds toneIndigo
```

## Components

### SOC workbench

- [Workbench UI](https://github.com/jashvanthan/sentineltrace/tree/master/frontend/src): `frontend/src`
- [Email review](https://github.com/jashvanthan/sentineltrace/blob/master/frontend/src/pages/EmailAnalysisPage.tsx): `frontend/src/pages/EmailAnalysisPage.tsx`
- [Campaign graph](https://github.com/jashvanthan/sentineltrace/blob/master/frontend/src/pages/CampaignGraphPage.tsx): `frontend/src/pages/CampaignGraphPage.tsx`
- [Infrastructure map](https://github.com/jashvanthan/sentineltrace/blob/master/frontend/src/pages/GeolocationPage.tsx): `frontend/src/pages/GeolocationPage.tsx`

### API and access

- [API application](https://github.com/jashvanthan/sentineltrace/blob/master/backend/app/main.py): `backend/app/main.py`
- [Authentication](https://github.com/jashvanthan/sentineltrace/blob/master/backend/app/api/v1/auth.py): `backend/app/api/v1/auth.py`
- [Email endpoints](https://github.com/jashvanthan/sentineltrace/blob/master/backend/app/api/v1/emails.py): `backend/app/api/v1/emails.py`
- [Workspace access](https://github.com/jashvanthan/sentineltrace/blob/master/backend/app/api/v1/workspaces.py): `backend/app/api/v1/workspaces.py`
- [Background worker](https://github.com/jashvanthan/sentineltrace/blob/master/backend/app/worker.py): `backend/app/worker.py`

### Email analysis

- [Threat orchestrator](https://github.com/jashvanthan/sentineltrace/blob/master/backend/app/services/threat_service.py): `backend/app/services/threat_service.py`
- [Email parsing](https://github.com/jashvanthan/sentineltrace/blob/master/backend/app/services/email_service.py): `backend/app/services/email_service.py`
- [AI classification](https://github.com/jashvanthan/sentineltrace/blob/master/backend/app/services/ai_service.py): `backend/app/services/ai_service.py`
- [Analysis agents](https://github.com/jashvanthan/sentineltrace/tree/master/backend/app/agents): `backend/app/agents`
- [Analysis records](https://github.com/jashvanthan/sentineltrace/blob/master/backend/app/models/email_analysis.py): `backend/app/models/email_analysis.py`

### Investigation and evidence

- [Threat intelligence](https://github.com/jashvanthan/sentineltrace/blob/master/backend/app/services/intel_service.py): `backend/app/services/intel_service.py`
- [Geolocation](https://github.com/jashvanthan/sentineltrace/blob/master/backend/app/services/geo_service.py): `backend/app/services/geo_service.py`
- [IP trace](https://github.com/jashvanthan/sentineltrace/blob/master/backend/app/services/ip_trace/service.py): `backend/app/services/ip_trace/service.py`
- [Campaign correlation](https://github.com/jashvanthan/sentineltrace/blob/master/backend/app/services/neo4j_service.py): `backend/app/services/neo4j_service.py`
- [Forensic reports](https://github.com/jashvanthan/sentineltrace/blob/master/backend/app/services/forensic_report_service.py): `backend/app/services/forensic_report_service.py`

### External integrations

- [Gmail integration](https://github.com/jashvanthan/sentineltrace/blob/master/backend/app/services/gmail_service.py): `backend/app/services/gmail_service.py`
- [Encrypted evidence storage](https://github.com/jashvanthan/sentineltrace/blob/master/backend/app/services/gcs_service.py): `backend/app/services/gcs_service.py`
- [MCP tool bridge](https://github.com/jashvanthan/sentineltrace/blob/master/mcp-server/src/server.py): `mcp-server/src/server.py`

### Other components

- **Responder**
- **LLM provider**
- **Threat intelligence providers**
- **PostgreSQL**

## Connections

- Responder → Workbench UI: uses
- Workbench UI → API application: requests API
- API application → Authentication: routes to (evidence: `backend/app/main.py`)
- API application → Email endpoints: routes to (evidence: `backend/app/main.py`)
- API application → Workspace access: routes to (evidence: `backend/app/main.py`)
- Email endpoints → Threat orchestrator: invokes (evidence: `backend/app/api/v1/emails.py`)
- Email endpoints → Background worker: queues analysis (evidence: `backend/app/api/v1/emails.py`)
- Background worker → Threat orchestrator: runs (evidence: `backend/app/worker.py`)
- Threat orchestrator → Email parsing: parses email (evidence: `backend/app/services/threat_service.py`)
- Threat orchestrator → AI classification: classifies (evidence: `backend/app/services/threat_service.py`)
- Threat orchestrator → Threat intelligence: enriches indicators (evidence: `backend/app/services/threat_service.py`)
- Threat orchestrator → Geolocation: enriches IPs (evidence: `backend/app/services/threat_service.py`)
- Threat orchestrator → Campaign correlation: updates graph (evidence: `backend/app/services/threat_service.py`)
- Threat orchestrator → Encrypted evidence storage: stores evidence (evidence: `backend/app/services/threat_service.py`)
- Threat orchestrator → Analysis records: records results (evidence: `backend/app/services/threat_service.py`)
- Email review → Analysis records: reviews
- Campaign graph → Campaign correlation: explores
- Infrastructure map → IP trace: visualizes
- Threat orchestrator → IP trace: traces infrastructure
- Threat orchestrator → Forensic reports: generates dossiers
- Gmail integration → Background worker: supplies messages (evidence: `backend/app/worker.py`)
- Threat intelligence providers → Threat intelligence: provides enrichment
- AI classification → LLM provider: requests analysis (evidence: `backend/app/services/ai_service.py`)
- MCP tool bridge → Email parsing: exposes tools (evidence: `mcp-server/src/server.py`)
- MCP tool bridge → Threat intelligence: exposes tools (evidence: `mcp-server/src/server.py`)
- MCP tool bridge → Geolocation: exposes tools (evidence: `mcp-server/src/server.py`)
- Authentication → PostgreSQL: stores sessions
- Analysis records → PostgreSQL: persists in
