# krrishvardhan/mailtraceai architecture

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

## Overview

mailTraceAI accepts raw .eml uploads, computes forensic and authentication signals, enriches probable origin IPs, runs ML classification and a Groq verdict, then returns and persists a case for dashboard review. The principal orchestration is explicit in the analysis route; dashboard visualization and history capabilities are documented, though some frontend wiring and implementation details were not excerpted. External service relationships reflect README documentation.

Main entry points: [`backend/email_routes.py`](https://github.com/krrishvardhan/mailtraceai/blob/main/backend/email_routes.py) (Analysis and cases), [`frontend/src/App.tsx`](https://github.com/krrishvardhan/mailtraceai/blob/main/frontend/src/App.tsx) (Analysis dashboard), [`backend/db/database.py`](https://github.com/krrishvardhan/mailtraceai/blob/main/backend/db/database.py) (Database access), [`frontend/src/lib/api.ts`](https://github.com/krrishvardhan/mailtraceai/blob/main/frontend/src/lib/api.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Investigation dashboard"]
  node_dashboard["Analysis dashboard<br/>[App.tsx]"]
  node_frontend_api["API client<br/>[api.ts]"]
  node_relay_view["Relay timeline"]
  node_origin_map["Origin map<br/>[IpLocationMap.tsx]"]
  node_charts["Risk charts"]
end

subgraph group_api["API orchestration"]
  node_api_app["FastAPI app<br/>[main.py]"]
  node_analysis_route["Analysis and cases<br/>[email_routes.py]"]
end

subgraph group_forensics["Email evidence"]
  node_email_forensics["Header forensics<br/>[email_forensics.py]"]
  node_geolocation["Origin assessment<br/>[geolocation.py]"]
end

subgraph group_verdict["Risk assessment"]
  node_feature_engineering["Feature extraction"]
  node_classifier["Phishing classifier"]
  node_llm_verdict["LLM verdict<br/>[llm_verdict.py]"]
end

subgraph group_persistence["Case persistence"]
  node_database_access["Database access<br/>[database.py]"]
  node_postgres[("Postgres case store")]
end

node_investigator(("Investigator"))
node_geo_service{{"IP geolocation"}}
node_groq{{"Groq API"}}

node_investigator -->|"uploads email"| node_dashboard
node_dashboard -.->|"requests analysis"| node_frontend_api
node_frontend_api -.->|"sends request"| node_api_app
node_api_app -->|"routes requests"| node_analysis_route
node_analysis_route -->|"checks cache"| node_database_access
node_analysis_route -->|"parses and analyzes"| node_email_forensics
node_analysis_route -->|"assesses origin"| node_geolocation
node_analysis_route -->|"geolocates IPs"| node_geo_service
node_analysis_route -->|"classifies email"| node_classifier
node_classifier -->|"extracts features"| node_feature_engineering
node_analysis_route -->|"requests verdict"| node_llm_verdict
node_llm_verdict -->|"requests synthesis"| node_groq
node_analysis_route -->|"stores analysis"| node_database_access
node_analysis_route -->|"lists or retrieves cases"| node_database_access
node_database_access -->|"reads and writes"| node_postgres
node_analysis_route -.->|"returns result"| node_dashboard
node_dashboard -.->|"renders relay hops"| node_relay_view
node_dashboard -.->|"renders origin map"| node_origin_map
node_dashboard -.->|"renders risk evidence"| node_charts

click node_dashboard "https://github.com/krrishvardhan/mailtraceai/blob/main/frontend/src/App.tsx"
click node_frontend_api "https://github.com/krrishvardhan/mailtraceai/blob/main/frontend/src/lib/api.ts"
click node_relay_view "https://github.com/krrishvardhan/mailtraceai/blob/main/frontend/src/components/RelayChainTimeline.tsx"
click node_origin_map "https://github.com/krrishvardhan/mailtraceai/blob/main/frontend/src/components/IpLocationMap.tsx"
click node_charts "https://github.com/krrishvardhan/mailtraceai/tree/main/frontend/src/components/charts"
click node_api_app "https://github.com/krrishvardhan/mailtraceai/blob/main/backend/main.py"
click node_analysis_route "https://github.com/krrishvardhan/mailtraceai/blob/main/backend/email_routes.py"
click node_email_forensics "https://github.com/krrishvardhan/mailtraceai/blob/main/backend/email_forensics.py"
click node_geolocation "https://github.com/krrishvardhan/mailtraceai/blob/main/backend/geolocation.py"
click node_feature_engineering "https://github.com/krrishvardhan/mailtraceai/blob/main/backend/ml/feature_engineering.py"
click node_classifier "https://github.com/krrishvardhan/mailtraceai/blob/main/backend/phishing_classifier.py"
click node_llm_verdict "https://github.com/krrishvardhan/mailtraceai/blob/main/backend/llm_verdict.py"
click node_database_access "https://github.com/krrishvardhan/mailtraceai/blob/main/backend/db/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_dashboard,node_frontend_api,node_relay_view,node_origin_map,node_charts toneBlue
class node_api_app,node_analysis_route toneAmber
class node_email_forensics,node_geolocation,node_groq toneMint
class node_feature_engineering,node_classifier,node_llm_verdict toneRose
class node_database_access,node_postgres,node_investigator,node_geo_service toneIndigo
```

## Components

### Investigation dashboard

- [Analysis dashboard](https://github.com/krrishvardhan/mailtraceai/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [API client](https://github.com/krrishvardhan/mailtraceai/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`
- [Relay timeline](https://github.com/krrishvardhan/mailtraceai/blob/main/frontend/src/components/RelayChainTimeline.tsx): `frontend/src/components/RelayChainTimeline.tsx`
- [Origin map](https://github.com/krrishvardhan/mailtraceai/blob/main/frontend/src/components/IpLocationMap.tsx): `frontend/src/components/IpLocationMap.tsx`
- [Risk charts](https://github.com/krrishvardhan/mailtraceai/tree/main/frontend/src/components/charts): `frontend/src/components/charts`

### API orchestration

- [FastAPI app](https://github.com/krrishvardhan/mailtraceai/blob/main/backend/main.py): `backend/main.py`
- [Analysis and cases](https://github.com/krrishvardhan/mailtraceai/blob/main/backend/email_routes.py): `backend/email_routes.py`

### Email evidence

- [Header forensics](https://github.com/krrishvardhan/mailtraceai/blob/main/backend/email_forensics.py): `backend/email_forensics.py`
- [Origin assessment](https://github.com/krrishvardhan/mailtraceai/blob/main/backend/geolocation.py): `backend/geolocation.py`

### Risk assessment

- [Feature extraction](https://github.com/krrishvardhan/mailtraceai/blob/main/backend/ml/feature_engineering.py): `backend/ml/feature_engineering.py`
- [Phishing classifier](https://github.com/krrishvardhan/mailtraceai/blob/main/backend/phishing_classifier.py): `backend/phishing_classifier.py`
- [LLM verdict](https://github.com/krrishvardhan/mailtraceai/blob/main/backend/llm_verdict.py): `backend/llm_verdict.py`

### Case persistence

- [Database access](https://github.com/krrishvardhan/mailtraceai/blob/main/backend/db/database.py): `backend/db/database.py`
- **Postgres case store**

### Other components

- **Investigator**
- **IP geolocation**
- **Groq API**

## Connections

- Investigator → Analysis dashboard: uploads email (evidence: `README.md`)
- Analysis dashboard → API client: requests analysis
- API client → FastAPI app: sends request
- FastAPI app → Analysis and cases: routes requests (evidence: `backend/main.py`)
- Analysis and cases → Database access: checks cache (evidence: `backend/email_routes.py`)
- Analysis and cases → Header forensics: parses and analyzes (evidence: `backend/email_routes.py`)
- Analysis and cases → Origin assessment: assesses origin (evidence: `backend/email_routes.py`)
- Analysis and cases → IP geolocation: geolocates IPs (evidence: `README.md`)
- Analysis and cases → Phishing classifier: classifies email (evidence: `backend/email_routes.py`)
- Phishing classifier → Feature extraction: extracts features (evidence: `backend/phishing_classifier.py`)
- Analysis and cases → LLM verdict: requests verdict (evidence: `backend/email_routes.py`)
- LLM verdict → Groq API: requests synthesis (evidence: `backend/llm_verdict.py`)
- Analysis and cases → Database access: stores analysis (evidence: `backend/email_routes.py`)
- Analysis and cases → Database access: lists or retrieves cases (evidence: `backend/email_routes.py`)
- Database access → Postgres case store: reads and writes (evidence: `README.md`)
- Analysis and cases → Analysis dashboard: returns result
- Analysis dashboard → Relay timeline: renders relay hops
- Analysis dashboard → Origin map: renders origin map
- Analysis dashboard → Risk charts: renders risk evidence
