# bhuvanbuilds/g-doc architecture

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

- Interactive diagram: https://gitdiagram.com/bhuvanbuilds/g-doc
- Repository: https://github.com/bhuvanbuilds/g-doc

## Overview

This is an email threat-investigation application: a user uploads an .eml file, the backend parses it, analyzes technical indicators, enriches evidence, and returns AI findings and a risk assessment for investigation views. The graph preserves the major backend analysis stages and the frontend’s dashboard, investigation, and authentication areas. Backend calls are supported by excerpts; frontend wiring is only partly visible, so uncertain connections are omitted or marked unverified.

Main entry points: [`backend/detection/evidence_engine.py`](https://github.com/bhuvanbuilds/g-doc/blob/main/backend/detection/evidence_engine.py) (Evidence Orchestrator), [`backend/main.py`](https://github.com/bhuvanbuilds/g-doc/blob/main/backend/main.py) (FastAPI Service), [`frontend/src/components/dashboard/upload-panel.tsx`](https://github.com/bhuvanbuilds/g-doc/blob/main/frontend/src/components/dashboard/upload-panel.tsx) (Email Upload), [`frontend/src/components/dashboard/dashboard-view.tsx`](https://github.com/bhuvanbuilds/g-doc/blob/main/frontend/src/components/dashboard/dashboard-view.tsx) (Dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Email Ingestion"]
  node_backend["FastAPI Service<br/>[main.py]"]
  node_parser["Email Parser<br/>[email_parser.py]"]
end

subgraph group_analysis["Evidence Analysis"]
  node_evidence["Evidence Orchestrator<br/>[evidence_engine.py]"]
  node_headers["Header Analysis<br/>[header_analysis.py]"]
  node_auth_analysis["Auth Analysis<br/>[auth_analysis.py]"]
  node_urls["URL Analysis<br/>[url_analysis.py]"]
  node_attachments["Attachment Analysis"]
  node_relay["Relay Analysis<br/>[relay_analysis.py]"]
  node_timeline["Timeline Analysis"]
  node_risk["Risk Assessment<br/>[risk_engine.py]"]
end

subgraph group_enrichment["Threat Enrichment"]
  node_groq["Semantic Analysis<br/>[groq.py]"]
  node_vt["VirusTotal Lookup<br/>[virustotal.py]"]
  node_ipinfo["IP Enrichment<br/>[ipinfo.py]"]
  node_gemini["Gemini Service<br/>[gemini.py]"]
end

subgraph group_frontend["Investigation Frontend"]
  node_web["Web Interface<br/>[page.tsx]"]
  node_upload["Email Upload<br/>[upload-panel.tsx]"]
  node_dashboard["Dashboard<br/>[dashboard-view.tsx]"]
  node_investigation_ui["Investigation Views"]
  node_derive["Result Derivation<br/>[derive.ts]"]
  node_history["Investigation History<br/>[history.ts]"]
  node_api["Investigation API<br/>[api.ts]"]
end

subgraph group_identity["Authentication"]
  node_supabase["Supabase Clients<br/>[server.ts]"]
  node_callback["Auth Callback<br/>[route.ts]"]
  node_signout["Sign Out<br/>[route.ts]"]
end

node_user(("Analyst"))

node_user -->|"uses"| node_web
node_web -->|"offers upload"| node_upload
node_upload -.->|"submits email"| node_api
node_api -.->|"requests investigation"| node_backend
node_backend -->|"parses email"| node_parser
node_backend -->|"builds evidence"| node_evidence
node_evidence -->|"analyzes headers"| node_headers
node_evidence -->|"analyzes auth"| node_auth_analysis
node_evidence -->|"analyzes URLs"| node_urls
node_evidence -->|"analyzes attachments"| node_attachments
node_evidence -->|"analyzes relays"| node_relay
node_evidence -->|"analyzes timeline"| node_timeline
node_evidence -->|"looks up URLs"| node_vt
node_evidence -->|"looks up IPs"| node_ipinfo
node_evidence -->|"requests semantic analysis"| node_groq
node_evidence -->|"calculates risk"| node_risk
node_dashboard -.->|"presents upload"| node_upload
node_dashboard -.->|"shows history"| node_history
node_investigation_ui -.->|"derives display data"| node_derive
node_derive -->|"uses history"| node_history

click node_web "https://github.com/bhuvanbuilds/g-doc/blob/main/frontend/src/app/page.tsx"
click node_upload "https://github.com/bhuvanbuilds/g-doc/blob/main/frontend/src/components/dashboard/upload-panel.tsx"
click node_dashboard "https://github.com/bhuvanbuilds/g-doc/blob/main/frontend/src/components/dashboard/dashboard-view.tsx"
click node_investigation_ui "https://github.com/bhuvanbuilds/g-doc/blob/main/frontend/src/components/investigation/investigation-view.tsx"
click node_derive "https://github.com/bhuvanbuilds/g-doc/blob/main/frontend/src/lib/derive.ts"
click node_history "https://github.com/bhuvanbuilds/g-doc/blob/main/frontend/src/lib/history.ts"
click node_api "https://github.com/bhuvanbuilds/g-doc/blob/main/frontend/src/lib/api.ts"
click node_backend "https://github.com/bhuvanbuilds/g-doc/blob/main/backend/main.py"
click node_parser "https://github.com/bhuvanbuilds/g-doc/blob/main/backend/parsers/email_parser.py"
click node_evidence "https://github.com/bhuvanbuilds/g-doc/blob/main/backend/detection/evidence_engine.py"
click node_headers "https://github.com/bhuvanbuilds/g-doc/blob/main/backend/parsers/header_analysis.py"
click node_auth_analysis "https://github.com/bhuvanbuilds/g-doc/blob/main/backend/parsers/auth_analysis.py"
click node_urls "https://github.com/bhuvanbuilds/g-doc/blob/main/backend/parsers/url_analysis.py"
click node_attachments "https://github.com/bhuvanbuilds/g-doc/blob/main/backend/parsers/attachment_analysis.py"
click node_relay "https://github.com/bhuvanbuilds/g-doc/blob/main/backend/parsers/relay_analysis.py"
click node_timeline "https://github.com/bhuvanbuilds/g-doc/blob/main/backend/parsers/timeline_analysis.py"
click node_risk "https://github.com/bhuvanbuilds/g-doc/blob/main/backend/detection/risk_engine.py"
click node_groq "https://github.com/bhuvanbuilds/g-doc/blob/main/backend/services/groq.py"
click node_vt "https://github.com/bhuvanbuilds/g-doc/blob/main/backend/services/virustotal.py"
click node_ipinfo "https://github.com/bhuvanbuilds/g-doc/blob/main/backend/services/ipinfo.py"
click node_gemini "https://github.com/bhuvanbuilds/g-doc/blob/main/backend/services/gemini.py"
click node_supabase "https://github.com/bhuvanbuilds/g-doc/blob/main/frontend/src/lib/supabase/server.ts"
click node_callback "https://github.com/bhuvanbuilds/g-doc/blob/main/frontend/src/app/auth/callback/route.ts"
click node_signout "https://github.com/bhuvanbuilds/g-doc/blob/main/frontend/src/app/auth/signout/route.ts"

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_backend,node_parser toneBlue
class node_evidence,node_headers,node_auth_analysis,node_urls,node_attachments,node_relay,node_timeline,node_risk toneAmber
class node_groq,node_vt,node_ipinfo,node_gemini toneMint
class node_web,node_upload,node_dashboard,node_investigation_ui,node_derive,node_history,node_api toneRose
class node_supabase,node_callback,node_signout,node_user toneIndigo
```

## Components

### Email Ingestion

- [FastAPI Service](https://github.com/bhuvanbuilds/g-doc/blob/main/backend/main.py): `backend/main.py`
- [Email Parser](https://github.com/bhuvanbuilds/g-doc/blob/main/backend/parsers/email_parser.py): `backend/parsers/email_parser.py`

### Evidence Analysis

- [Evidence Orchestrator](https://github.com/bhuvanbuilds/g-doc/blob/main/backend/detection/evidence_engine.py): `backend/detection/evidence_engine.py`
- [Header Analysis](https://github.com/bhuvanbuilds/g-doc/blob/main/backend/parsers/header_analysis.py): `backend/parsers/header_analysis.py`
- [Auth Analysis](https://github.com/bhuvanbuilds/g-doc/blob/main/backend/parsers/auth_analysis.py): `backend/parsers/auth_analysis.py`
- [URL Analysis](https://github.com/bhuvanbuilds/g-doc/blob/main/backend/parsers/url_analysis.py): `backend/parsers/url_analysis.py`
- [Attachment Analysis](https://github.com/bhuvanbuilds/g-doc/blob/main/backend/parsers/attachment_analysis.py): `backend/parsers/attachment_analysis.py`
- [Relay Analysis](https://github.com/bhuvanbuilds/g-doc/blob/main/backend/parsers/relay_analysis.py): `backend/parsers/relay_analysis.py`
- [Timeline Analysis](https://github.com/bhuvanbuilds/g-doc/blob/main/backend/parsers/timeline_analysis.py): `backend/parsers/timeline_analysis.py`
- [Risk Assessment](https://github.com/bhuvanbuilds/g-doc/blob/main/backend/detection/risk_engine.py): `backend/detection/risk_engine.py`

### Threat Enrichment

- [Semantic Analysis](https://github.com/bhuvanbuilds/g-doc/blob/main/backend/services/groq.py): `backend/services/groq.py`
- [VirusTotal Lookup](https://github.com/bhuvanbuilds/g-doc/blob/main/backend/services/virustotal.py): `backend/services/virustotal.py`
- [IP Enrichment](https://github.com/bhuvanbuilds/g-doc/blob/main/backend/services/ipinfo.py): `backend/services/ipinfo.py`
- [Gemini Service](https://github.com/bhuvanbuilds/g-doc/blob/main/backend/services/gemini.py): `backend/services/gemini.py`

### Investigation Frontend

- [Web Interface](https://github.com/bhuvanbuilds/g-doc/blob/main/frontend/src/app/page.tsx): `frontend/src/app/page.tsx`
- [Email Upload](https://github.com/bhuvanbuilds/g-doc/blob/main/frontend/src/components/dashboard/upload-panel.tsx): `frontend/src/components/dashboard/upload-panel.tsx`
- [Dashboard](https://github.com/bhuvanbuilds/g-doc/blob/main/frontend/src/components/dashboard/dashboard-view.tsx): `frontend/src/components/dashboard/dashboard-view.tsx`
- [Investigation Views](https://github.com/bhuvanbuilds/g-doc/blob/main/frontend/src/components/investigation/investigation-view.tsx): `frontend/src/components/investigation/investigation-view.tsx`
- [Result Derivation](https://github.com/bhuvanbuilds/g-doc/blob/main/frontend/src/lib/derive.ts): `frontend/src/lib/derive.ts`
- [Investigation History](https://github.com/bhuvanbuilds/g-doc/blob/main/frontend/src/lib/history.ts): `frontend/src/lib/history.ts`
- [Investigation API](https://github.com/bhuvanbuilds/g-doc/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`

### Authentication

- [Supabase Clients](https://github.com/bhuvanbuilds/g-doc/blob/main/frontend/src/lib/supabase/server.ts): `frontend/src/lib/supabase/server.ts`
- [Auth Callback](https://github.com/bhuvanbuilds/g-doc/blob/main/frontend/src/app/auth/callback/route.ts): `frontend/src/app/auth/callback/route.ts`
- [Sign Out](https://github.com/bhuvanbuilds/g-doc/blob/main/frontend/src/app/auth/signout/route.ts): `frontend/src/app/auth/signout/route.ts`

### Other components

- **Analyst**

## Connections

- Analyst → Web Interface: uses
- Web Interface → Email Upload: offers upload
- Email Upload → Investigation API: submits email
- Investigation API → FastAPI Service: requests investigation
- FastAPI Service → Email Parser: parses email (evidence: `backend/main.py`)
- FastAPI Service → Evidence Orchestrator: builds evidence (evidence: `backend/main.py`)
- Evidence Orchestrator → Header Analysis: analyzes headers (evidence: `backend/detection/evidence_engine.py`)
- Evidence Orchestrator → Auth Analysis: analyzes auth (evidence: `backend/detection/evidence_engine.py`)
- Evidence Orchestrator → URL Analysis: analyzes URLs (evidence: `backend/detection/evidence_engine.py`)
- Evidence Orchestrator → Attachment Analysis: analyzes attachments (evidence: `backend/detection/evidence_engine.py`)
- Evidence Orchestrator → Relay Analysis: analyzes relays (evidence: `backend/detection/evidence_engine.py`)
- Evidence Orchestrator → Timeline Analysis: analyzes timeline (evidence: `backend/detection/evidence_engine.py`)
- Evidence Orchestrator → VirusTotal Lookup: looks up URLs (evidence: `backend/detection/evidence_engine.py`)
- Evidence Orchestrator → IP Enrichment: looks up IPs (evidence: `backend/detection/evidence_engine.py`)
- Evidence Orchestrator → Semantic Analysis: requests semantic analysis (evidence: `backend/detection/evidence_engine.py`)
- Evidence Orchestrator → Risk Assessment: calculates risk (evidence: `backend/detection/evidence_engine.py`)
- Dashboard → Email Upload: presents upload
- Dashboard → Investigation History: shows history
- Investigation Views → Result Derivation: derives display data
- Result Derivation → Investigation History: uses history (evidence: `frontend/src/lib/derive.ts`)
