# 25a31a05gb/tracexmail architecture

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

## Overview

TraceX is an email-forensics and threat-triage application: analysts ingest an email or connect Gmail, receive a normalized analysis with threat and network context, then investigate cases, alerts, and evidence in the workspace. The map shows the client-to-server analysis path, plus major documented UI and service capabilities. Several backend and workspace relationships rely on the SOURCE INDEX rather than complete excerpts; uncertain links are omitted or marked dashed.

Main entry points: [`server.ts`](https://github.com/25a31a05gb/tracexmail/blob/main/server.ts) (API & Ingestion), [`src/lib/api.ts`](https://github.com/25a31a05gb/tracexmail/blob/main/src/lib/api.ts) (Analysis API), [`src/App.tsx`](https://github.com/25a31a05gb/tracexmail/blob/main/src/App.tsx) (Workspace Shell), [`src/components/GmailConnectionView.tsx`](https://github.com/25a31a05gb/tracexmail/blob/main/src/components/GmailConnectionView.tsx) (Gmail Connection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Analyst Workspace"]
  node_app["Workspace Shell<br/>[App.tsx]"]
  node_ingest["Email Ingestion"]
  node_gmail_ui["Gmail Connection"]
  node_investigation["Cases &amp; Investigation<br/>[CasesView.tsx]"]
  node_alerts_ui["Alerts &amp; Timeline<br/>[AlertsView.tsx]"]
end

subgraph group_analysis["Email Analysis"]
  node_analysis_api["Analysis API<br/>[api.ts]"]
  node_email_parser["Email Parser<br/>[parser.ts]"]
  node_classifier["Threat Classifier<br/>[classifier.ts]"]
  node_analysis_types["Analysis Model<br/>[types.ts]"]
  node_api_server["API &amp; Ingestion<br/>[server.ts]"]
end

subgraph group_intel["Threat Intelligence"]
  node_network_intel["Network Intelligence<br/>[index.ts]"]
  node_domain_intel["Domain Intelligence<br/>[domainService.ts]"]
  node_rdap["RDAP Lookup<br/>[rdap.ts]"]
  node_correlation["Threat Correlation"]
end

subgraph group_operations["SOC Operations"]
  node_gmail_service["Gmail Service<br/>[gmailService.ts]"]
  node_pubsub["Gmail Pub/Sub<br/>[gmailPubSub.ts]"]
  node_compliance["Audit &amp; Compliance<br/>[compliance.ts]"]
  node_live_threats["Live Threat Feed"]
  node_ws_alerts["Realtime Alerts"]
end

subgraph group_platform["Identity &amp; Platform"]
  node_auth_routes["Authentication Routes<br/>[authRoutes.ts]"]
  node_profile_store["User Profiles"]
  node_org_store["Organization Users<br/>[orgUserStore.ts]"]
  node_server_store[("Supabase Store<br/>[supabase.ts]")]
  node_client_store["Client Supabase<br/>[supabase.ts]"]
end

node_analyst(("Analyst"))

node_analyst -->|"uses workspace"| node_app
node_app -->|"routes to"| node_ingest
node_analyst -.->|"connects inbox"| node_gmail_ui
node_ingest -->|"submits email"| node_analysis_api
node_ingest -->|"parses fallback"| node_email_parser
node_analysis_api -->|"uses credentials"| node_client_store
node_analysis_api -.->|"calls API"| node_api_server
node_api_server -.->|"dispatches analysis"| node_classifier
node_api_server -.->|"queries intelligence"| node_network_intel
node_api_server -->|"uses decoding helpers"| node_email_parser
node_network_intel -->|"dispatches lookup"| node_rdap
node_api_server -->|"queries domains"| node_domain_intel
node_domain_intel -->|"uses lookup"| node_rdap
node_api_server -->|"fetches feed"| node_live_threats
node_gmail_ui -->|"uses API client"| node_analysis_api
node_gmail_ui -->|"parses messages"| node_email_parser
node_gmail_ui -->|"uses subscription"| node_pubsub
node_pubsub -->|"calls API"| node_analysis_api
node_api_server -->|"fetches Gmail mail"| node_gmail_service
node_app -.->|"presents cases"| node_investigation
node_app -.->|"presents alerts"| node_alerts_ui
node_alerts_ui -->|"subscribes alerts"| node_ws_alerts
node_ws_alerts -->|"streams changes"| node_client_store
node_api_server -->|"loads privacy config"| node_compliance
node_auth_routes -->|"audits actions"| node_compliance
node_auth_routes -->|"saves profiles"| node_profile_store
node_auth_routes -->|"manages org users"| node_org_store
node_compliance -->|"resolves profiles"| node_profile_store
node_compliance -->|"persists compliance data"| node_server_store
node_profile_store -->|"uses database"| node_server_store
node_org_store -->|"uses database"| node_server_store

click node_app "https://github.com/25a31a05gb/tracexmail/blob/main/src/App.tsx"
click node_ingest "https://github.com/25a31a05gb/tracexmail/blob/main/src/components/IngestionPipelineView.tsx"
click node_gmail_ui "https://github.com/25a31a05gb/tracexmail/blob/main/src/components/GmailConnectionView.tsx"
click node_investigation "https://github.com/25a31a05gb/tracexmail/blob/main/src/components/CasesView.tsx"
click node_alerts_ui "https://github.com/25a31a05gb/tracexmail/blob/main/src/components/AlertsView.tsx"
click node_analysis_api "https://github.com/25a31a05gb/tracexmail/blob/main/src/lib/api.ts"
click node_email_parser "https://github.com/25a31a05gb/tracexmail/blob/main/src/utils/parser.ts"
click node_classifier "https://github.com/25a31a05gb/tracexmail/blob/main/src/server/classifier.ts"
click node_analysis_types "https://github.com/25a31a05gb/tracexmail/blob/main/src/types.ts"
click node_api_server "https://github.com/25a31a05gb/tracexmail/blob/main/server.ts"
click node_network_intel "https://github.com/25a31a05gb/tracexmail/blob/main/src/server/intelligence/index.ts"
click node_domain_intel "https://github.com/25a31a05gb/tracexmail/blob/main/src/server/domainService.ts"
click node_rdap "https://github.com/25a31a05gb/tracexmail/blob/main/src/server/intelligence/rdap.ts"
click node_correlation "https://github.com/25a31a05gb/tracexmail/blob/main/src/server/correlationEngine.ts"
click node_gmail_service "https://github.com/25a31a05gb/tracexmail/blob/main/src/server/gmailService.ts"
click node_pubsub "https://github.com/25a31a05gb/tracexmail/blob/main/src/services/gmailPubSub.ts"
click node_compliance "https://github.com/25a31a05gb/tracexmail/blob/main/src/server/compliance.ts"
click node_live_threats "https://github.com/25a31a05gb/tracexmail/blob/main/src/server/realWorldThreatService.ts"
click node_auth_routes "https://github.com/25a31a05gb/tracexmail/blob/main/src/server/authRoutes.ts"
click node_profile_store "https://github.com/25a31a05gb/tracexmail/blob/main/src/server/userProfileStore.ts"
click node_org_store "https://github.com/25a31a05gb/tracexmail/blob/main/src/server/orgUserStore.ts"
click node_server_store "https://github.com/25a31a05gb/tracexmail/blob/main/src/server/supabase.ts"
click node_client_store "https://github.com/25a31a05gb/tracexmail/blob/main/src/lib/supabase.ts"
click node_ws_alerts "https://github.com/25a31a05gb/tracexmail/blob/main/src/hooks/useWebSocketAlerts.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_app,node_ingest,node_gmail_ui,node_investigation,node_alerts_ui toneBlue
class node_analysis_api,node_email_parser,node_classifier,node_analysis_types,node_api_server toneAmber
class node_network_intel,node_domain_intel,node_rdap,node_correlation toneMint
class node_gmail_service,node_pubsub,node_compliance,node_live_threats,node_ws_alerts toneRose
class node_auth_routes,node_profile_store,node_org_store,node_server_store,node_client_store,node_analyst toneIndigo
```

## Components

### Analyst Workspace

- [Workspace Shell](https://github.com/25a31a05gb/tracexmail/blob/main/src/App.tsx): `src/App.tsx`
- [Email Ingestion](https://github.com/25a31a05gb/tracexmail/blob/main/src/components/IngestionPipelineView.tsx): `src/components/IngestionPipelineView.tsx`
- [Gmail Connection](https://github.com/25a31a05gb/tracexmail/blob/main/src/components/GmailConnectionView.tsx): `src/components/GmailConnectionView.tsx`
- [Cases & Investigation](https://github.com/25a31a05gb/tracexmail/blob/main/src/components/CasesView.tsx): `src/components/CasesView.tsx`
- [Alerts & Timeline](https://github.com/25a31a05gb/tracexmail/blob/main/src/components/AlertsView.tsx): `src/components/AlertsView.tsx`

### Email Analysis

- [Analysis API](https://github.com/25a31a05gb/tracexmail/blob/main/src/lib/api.ts): `src/lib/api.ts`
- [Email Parser](https://github.com/25a31a05gb/tracexmail/blob/main/src/utils/parser.ts): `src/utils/parser.ts`
- [Threat Classifier](https://github.com/25a31a05gb/tracexmail/blob/main/src/server/classifier.ts): `src/server/classifier.ts`
- [Analysis Model](https://github.com/25a31a05gb/tracexmail/blob/main/src/types.ts): `src/types.ts`
- [API & Ingestion](https://github.com/25a31a05gb/tracexmail/blob/main/server.ts): `server.ts`

### Threat Intelligence

- [Network Intelligence](https://github.com/25a31a05gb/tracexmail/blob/main/src/server/intelligence/index.ts): `src/server/intelligence/index.ts`
- [Domain Intelligence](https://github.com/25a31a05gb/tracexmail/blob/main/src/server/domainService.ts): `src/server/domainService.ts`
- [RDAP Lookup](https://github.com/25a31a05gb/tracexmail/blob/main/src/server/intelligence/rdap.ts): `src/server/intelligence/rdap.ts`
- [Threat Correlation](https://github.com/25a31a05gb/tracexmail/blob/main/src/server/correlationEngine.ts): `src/server/correlationEngine.ts`

### SOC Operations

- [Gmail Service](https://github.com/25a31a05gb/tracexmail/blob/main/src/server/gmailService.ts): `src/server/gmailService.ts`
- [Gmail Pub/Sub](https://github.com/25a31a05gb/tracexmail/blob/main/src/services/gmailPubSub.ts): `src/services/gmailPubSub.ts`
- [Audit & Compliance](https://github.com/25a31a05gb/tracexmail/blob/main/src/server/compliance.ts): `src/server/compliance.ts`
- [Live Threat Feed](https://github.com/25a31a05gb/tracexmail/blob/main/src/server/realWorldThreatService.ts): `src/server/realWorldThreatService.ts`
- [Realtime Alerts](https://github.com/25a31a05gb/tracexmail/blob/main/src/hooks/useWebSocketAlerts.ts): `src/hooks/useWebSocketAlerts.ts`

### Identity & Platform

- [Authentication Routes](https://github.com/25a31a05gb/tracexmail/blob/main/src/server/authRoutes.ts): `src/server/authRoutes.ts`
- [User Profiles](https://github.com/25a31a05gb/tracexmail/blob/main/src/server/userProfileStore.ts): `src/server/userProfileStore.ts`
- [Organization Users](https://github.com/25a31a05gb/tracexmail/blob/main/src/server/orgUserStore.ts): `src/server/orgUserStore.ts`
- [Supabase Store](https://github.com/25a31a05gb/tracexmail/blob/main/src/server/supabase.ts): `src/server/supabase.ts`
- [Client Supabase](https://github.com/25a31a05gb/tracexmail/blob/main/src/lib/supabase.ts): `src/lib/supabase.ts`

### Other components

- **Analyst**

## Connections

- Analyst → Workspace Shell: uses workspace (evidence: `src/App.tsx`)
- Workspace Shell → Email Ingestion: routes to (evidence: `src/App.tsx`)
- Analyst → Gmail Connection: connects inbox
- Email Ingestion → Analysis API: submits email (evidence: `src/components/IngestionPipelineView.tsx`)
- Email Ingestion → Email Parser: parses fallback (evidence: `src/components/IngestionPipelineView.tsx`)
- Analysis API → Client Supabase: uses credentials (evidence: `src/lib/api.ts`)
- Analysis API → API & Ingestion: calls API
- API & Ingestion → Threat Classifier: dispatches analysis (evidence: `server.ts`)
- API & Ingestion → Network Intelligence: queries intelligence (evidence: `server.ts`)
- API & Ingestion → Email Parser: uses decoding helpers (evidence: `server.ts`)
- Network Intelligence → RDAP Lookup: dispatches lookup (evidence: `src/server/intelligence/index.ts`)
- API & Ingestion → Domain Intelligence: queries domains (evidence: `server.ts`)
- Domain Intelligence → RDAP Lookup: uses lookup (evidence: `src/server/domainService.ts`)
- API & Ingestion → Live Threat Feed: fetches feed (evidence: `server.ts`)
- Gmail Connection → Analysis API: uses API client (evidence: `src/components/GmailConnectionView.tsx`)
- Gmail Connection → Email Parser: parses messages (evidence: `src/components/GmailConnectionView.tsx`)
- Gmail Connection → Gmail Pub/Sub: uses subscription (evidence: `src/components/GmailConnectionView.tsx`)
- Gmail Pub/Sub → Analysis API: calls API (evidence: `src/services/gmailPubSub.ts`)
- API & Ingestion → Gmail Service: fetches Gmail mail (evidence: `server.ts`)
- Workspace Shell → Cases & Investigation: presents cases (evidence: `src/App.tsx`)
- Workspace Shell → Alerts & Timeline: presents alerts (evidence: `src/App.tsx`)
- Alerts & Timeline → Realtime Alerts: subscribes alerts
- Realtime Alerts → Client Supabase: streams changes (evidence: `src/hooks/useWebSocketAlerts.ts`)
- API & Ingestion → Audit & Compliance: loads privacy config (evidence: `server.ts`)
- Authentication Routes → Audit & Compliance: audits actions (evidence: `src/server/authRoutes.ts`)
- Authentication Routes → User Profiles: saves profiles (evidence: `src/server/authRoutes.ts`)
- Authentication Routes → Organization Users: manages org users (evidence: `src/server/authRoutes.ts`)
- Audit & Compliance → User Profiles: resolves profiles (evidence: `src/server/compliance.ts`)
- Audit & Compliance → Supabase Store: persists compliance data (evidence: `src/server/compliance.ts`)
- User Profiles → Supabase Store: uses database (evidence: `src/server/userProfileStore.ts`)
- Organization Users → Supabase Store: uses database (evidence: `src/server/orgUserStore.ts`)
