# yohan-987/tracemail architecture

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

## Overview

This is an email-threat investigation product: analysts authenticate, ingest or retrieve email evidence, review forensic and risk assessments, and explore cases, infrastructure, AI findings, and reports. The backend’s documented ingest pipeline preserves the original message, parses it, runs independent analyses, computes risk, and stores a record; authenticated API routes expose investigation and Gmail workflows. The frontend routes to investigation workspaces and supporting views. Several frontend pages and backend routes were not sampled, so their internal wiring is not asserted.

Main entry points: [`FRONTEND/src/App.tsx`](https://github.com/yohan-987/tracemail/blob/main/FRONTEND/src/App.tsx) (App routes), [`backend-batch3.5/backend/src/services/emailIngestPipeline.ts`](https://github.com/yohan-987/tracemail/blob/main/backend-batch3.5/backend/src/services/emailIngestPipeline.ts) (Ingest pipeline), [`backend-batch3.5/backend/src/routes/emails.ts`](https://github.com/yohan-987/tracemail/blob/main/backend-batch3.5/backend/src/routes/emails.ts) (Email API), [`backend-batch3.5/backend/src/app.ts`](https://github.com/yohan-987/tracemail/blob/main/backend-batch3.5/backend/src/app.ts) (API application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Analyst frontend"]
  node_app["App routes<br/>[App.tsx]"]
  node_authui["Session context<br/>[AuthContext.tsx]"]
  node_caseui["Active case"]
  node_scanner["Email scanner<br/>[ScannerPage.tsx]"]
  node_investigation["Investigation views"]
  node_infrastructureui["Infrastructure view"]
  node_casesui["Case management<br/>[CasesPage.tsx]"]
  node_reportsui["Reports view<br/>[ReportsPage.tsx]"]
  node_apiclient["API client<br/>[api.ts]"]
end

subgraph group_api["API and access"]
  node_server["HTTP server<br/>[server.ts]"]
  node_appbackend["API application<br/>[app.ts]"]
  node_authroutes["Authentication routes<br/>[auth.ts]"]
  node_authgate["Session gate<br/>[requireAuth.ts]"]
  node_emailroutes["Email API<br/>[emails.ts]"]
  node_gmailroutes["Gmail API<br/>[gmail.ts]"]
end

subgraph group_ingest["Evidence ingestion"]
  node_ingestpipe["Ingest pipeline"]
  node_parser["Email parser<br/>[emailParser.ts]"]
end

subgraph group_analysis["Threat analysis"]
  node_forensics["Header forensics<br/>[headerForensics.ts]"]
  node_risk["Risk engine<br/>[riskEngine.ts]"]
  node_aiassessment["AI assessment<br/>[aiAssessment.ts]"]
  node_infraanalysis["Infrastructure analysis<br/>[infrastructure.ts]"]
end

subgraph group_persistence["Evidence and services"]
  node_emailstore[("Email store<br/>[emailStore.ts]")]
  node_emailquery["Email queries<br/>[emailQuery.ts]"]
  node_llm["LLM provider client<br/>[llmClient.ts]"]
  node_schemas["Domain schemas<br/>[types.ts]"]
end

node_analyst(("Analyst"))

node_analyst -.->|"uses"| node_app
node_app -->|"provides session"| node_authui
node_app -->|"routes to"| node_scanner
node_app -->|"routes to"| node_investigation
node_app -->|"routes to"| node_infrastructureui
node_app -->|"routes to"| node_casesui
node_app -->|"routes to"| node_reportsui
node_app -->|"mounts after auth"| node_caseui
node_app -.->|"API use"| node_apiclient
node_apiclient -.->|"HTTP requests"| node_server
node_server -->|"creates and serves"| node_appbackend
node_appbackend -->|"mounts"| node_authroutes
node_appbackend -->|"mounts"| node_emailroutes
node_appbackend -->|"mounts"| node_gmailroutes
node_emailroutes -->|"protects routes"| node_authgate
node_emailroutes -->|"ingests email"| node_ingestpipe
node_emailroutes -->|"queries records"| node_emailquery
node_emailroutes -->|"reads and writes"| node_emailstore
node_gmailroutes -.->|"protects routes"| node_authgate
node_ingestpipe -->|"parses message"| node_parser
node_ingestpipe -->|"analyzes headers"| node_forensics
node_ingestpipe -->|"computes risk"| node_risk
node_ingestpipe -->|"assesses with AI"| node_aiassessment
node_ingestpipe -->|"checks infrastructure"| node_infraanalysis
node_ingestpipe -->|"stores evidence"| node_emailstore
node_aiassessment -->|"uses provider"| node_llm
node_ingestpipe -.->|"builds typed record"| node_schemas
node_emailquery -->|"uses types"| node_schemas

click node_app "https://github.com/yohan-987/tracemail/blob/main/FRONTEND/src/App.tsx"
click node_authui "https://github.com/yohan-987/tracemail/blob/main/FRONTEND/src/context/AuthContext.tsx"
click node_caseui "https://github.com/yohan-987/tracemail/blob/main/FRONTEND/src/context/ActiveCaseContext.tsx"
click node_scanner "https://github.com/yohan-987/tracemail/blob/main/FRONTEND/src/pages/ScannerPage.tsx"
click node_investigation "https://github.com/yohan-987/tracemail/blob/main/FRONTEND/src/pages/AIInvestigationPage.tsx"
click node_infrastructureui "https://github.com/yohan-987/tracemail/blob/main/FRONTEND/src/pages/InfrastructurePage.tsx"
click node_casesui "https://github.com/yohan-987/tracemail/blob/main/FRONTEND/src/pages/CasesPage.tsx"
click node_reportsui "https://github.com/yohan-987/tracemail/blob/main/FRONTEND/src/pages/ReportsPage.tsx"
click node_apiclient "https://github.com/yohan-987/tracemail/blob/main/FRONTEND/src/api/api.ts"
click node_server "https://github.com/yohan-987/tracemail/blob/main/backend-batch3.5/backend/src/server.ts"
click node_appbackend "https://github.com/yohan-987/tracemail/blob/main/backend-batch3.5/backend/src/app.ts"
click node_authroutes "https://github.com/yohan-987/tracemail/blob/main/backend-batch3.5/backend/src/routes/auth.ts"
click node_authgate "https://github.com/yohan-987/tracemail/blob/main/backend-batch3.5/backend/src/middleware/requireAuth.ts"
click node_emailroutes "https://github.com/yohan-987/tracemail/blob/main/backend-batch3.5/backend/src/routes/emails.ts"
click node_gmailroutes "https://github.com/yohan-987/tracemail/blob/main/backend-batch3.5/backend/src/routes/gmail.ts"
click node_ingestpipe "https://github.com/yohan-987/tracemail/blob/main/backend-batch3.5/backend/src/services/emailIngestPipeline.ts"
click node_parser "https://github.com/yohan-987/tracemail/blob/main/backend-batch3.5/backend/src/analyzers/emailParser.ts"
click node_forensics "https://github.com/yohan-987/tracemail/blob/main/backend-batch3.5/backend/src/analyzers/headerForensics.ts"
click node_risk "https://github.com/yohan-987/tracemail/blob/main/backend-batch3.5/backend/src/analyzers/riskEngine.ts"
click node_aiassessment "https://github.com/yohan-987/tracemail/blob/main/backend-batch3.5/backend/src/analyzers/aiAssessment.ts"
click node_infraanalysis "https://github.com/yohan-987/tracemail/blob/main/backend-batch3.5/backend/src/analyzers/infrastructure.ts"
click node_emailstore "https://github.com/yohan-987/tracemail/blob/main/backend-batch3.5/backend/src/services/emailStore.ts"
click node_emailquery "https://github.com/yohan-987/tracemail/blob/main/backend-batch3.5/backend/src/services/emailQuery.ts"
click node_llm "https://github.com/yohan-987/tracemail/blob/main/backend-batch3.5/backend/src/services/llmClient.ts"
click node_schemas "https://github.com/yohan-987/tracemail/blob/main/backend-batch3.5/backend/src/schemas/types.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_authui,node_caseui,node_scanner,node_investigation,node_infrastructureui,node_casesui,node_reportsui,node_apiclient toneBlue
class node_server,node_appbackend,node_authroutes,node_authgate,node_emailroutes,node_gmailroutes toneAmber
class node_ingestpipe,node_parser toneMint
class node_forensics,node_risk,node_aiassessment,node_infraanalysis toneRose
class node_emailstore,node_emailquery,node_llm,node_schemas,node_analyst toneIndigo
```

## Components

### Analyst frontend

- [App routes](https://github.com/yohan-987/tracemail/blob/main/FRONTEND/src/App.tsx): `FRONTEND/src/App.tsx`
- [Session context](https://github.com/yohan-987/tracemail/blob/main/FRONTEND/src/context/AuthContext.tsx): `FRONTEND/src/context/AuthContext.tsx`
- [Active case](https://github.com/yohan-987/tracemail/blob/main/FRONTEND/src/context/ActiveCaseContext.tsx): `FRONTEND/src/context/ActiveCaseContext.tsx`
- [Email scanner](https://github.com/yohan-987/tracemail/blob/main/FRONTEND/src/pages/ScannerPage.tsx): `FRONTEND/src/pages/ScannerPage.tsx`
- [Investigation views](https://github.com/yohan-987/tracemail/blob/main/FRONTEND/src/pages/AIInvestigationPage.tsx): `FRONTEND/src/pages/AIInvestigationPage.tsx`
- [Infrastructure view](https://github.com/yohan-987/tracemail/blob/main/FRONTEND/src/pages/InfrastructurePage.tsx): `FRONTEND/src/pages/InfrastructurePage.tsx`
- [Case management](https://github.com/yohan-987/tracemail/blob/main/FRONTEND/src/pages/CasesPage.tsx): `FRONTEND/src/pages/CasesPage.tsx`
- [Reports view](https://github.com/yohan-987/tracemail/blob/main/FRONTEND/src/pages/ReportsPage.tsx): `FRONTEND/src/pages/ReportsPage.tsx`
- [API client](https://github.com/yohan-987/tracemail/blob/main/FRONTEND/src/api/api.ts): `FRONTEND/src/api/api.ts`

### API and access

- [HTTP server](https://github.com/yohan-987/tracemail/blob/main/backend-batch3.5/backend/src/server.ts): `backend-batch3.5/backend/src/server.ts`
- [API application](https://github.com/yohan-987/tracemail/blob/main/backend-batch3.5/backend/src/app.ts): `backend-batch3.5/backend/src/app.ts`
- [Authentication routes](https://github.com/yohan-987/tracemail/blob/main/backend-batch3.5/backend/src/routes/auth.ts): `backend-batch3.5/backend/src/routes/auth.ts`
- [Session gate](https://github.com/yohan-987/tracemail/blob/main/backend-batch3.5/backend/src/middleware/requireAuth.ts): `backend-batch3.5/backend/src/middleware/requireAuth.ts`
- [Email API](https://github.com/yohan-987/tracemail/blob/main/backend-batch3.5/backend/src/routes/emails.ts): `backend-batch3.5/backend/src/routes/emails.ts`
- [Gmail API](https://github.com/yohan-987/tracemail/blob/main/backend-batch3.5/backend/src/routes/gmail.ts): `backend-batch3.5/backend/src/routes/gmail.ts`

### Evidence ingestion

- [Ingest pipeline](https://github.com/yohan-987/tracemail/blob/main/backend-batch3.5/backend/src/services/emailIngestPipeline.ts): `backend-batch3.5/backend/src/services/emailIngestPipeline.ts`
- [Email parser](https://github.com/yohan-987/tracemail/blob/main/backend-batch3.5/backend/src/analyzers/emailParser.ts): `backend-batch3.5/backend/src/analyzers/emailParser.ts`

### Threat analysis

- [Header forensics](https://github.com/yohan-987/tracemail/blob/main/backend-batch3.5/backend/src/analyzers/headerForensics.ts): `backend-batch3.5/backend/src/analyzers/headerForensics.ts`
- [Risk engine](https://github.com/yohan-987/tracemail/blob/main/backend-batch3.5/backend/src/analyzers/riskEngine.ts): `backend-batch3.5/backend/src/analyzers/riskEngine.ts`
- [AI assessment](https://github.com/yohan-987/tracemail/blob/main/backend-batch3.5/backend/src/analyzers/aiAssessment.ts): `backend-batch3.5/backend/src/analyzers/aiAssessment.ts`
- [Infrastructure analysis](https://github.com/yohan-987/tracemail/blob/main/backend-batch3.5/backend/src/analyzers/infrastructure.ts): `backend-batch3.5/backend/src/analyzers/infrastructure.ts`

### Evidence and services

- [Email store](https://github.com/yohan-987/tracemail/blob/main/backend-batch3.5/backend/src/services/emailStore.ts): `backend-batch3.5/backend/src/services/emailStore.ts`
- [Email queries](https://github.com/yohan-987/tracemail/blob/main/backend-batch3.5/backend/src/services/emailQuery.ts): `backend-batch3.5/backend/src/services/emailQuery.ts`
- [LLM provider client](https://github.com/yohan-987/tracemail/blob/main/backend-batch3.5/backend/src/services/llmClient.ts): `backend-batch3.5/backend/src/services/llmClient.ts`
- [Domain schemas](https://github.com/yohan-987/tracemail/blob/main/backend-batch3.5/backend/src/schemas/types.ts): `backend-batch3.5/backend/src/schemas/types.ts`

### Other components

- **Analyst**

## Connections

- Analyst → App routes: uses
- App routes → Session context: provides session (evidence: `FRONTEND/src/App.tsx`)
- App routes → Email scanner: routes to (evidence: `FRONTEND/src/App.tsx`)
- App routes → Investigation views: routes to (evidence: `FRONTEND/src/App.tsx`)
- App routes → Infrastructure view: routes to (evidence: `FRONTEND/src/App.tsx`)
- App routes → Case management: routes to (evidence: `FRONTEND/src/App.tsx`)
- App routes → Reports view: routes to (evidence: `FRONTEND/src/App.tsx`)
- App routes → Active case: mounts after auth (evidence: `FRONTEND/src/App.tsx`)
- App routes → API client: API use
- API client → HTTP server: HTTP requests
- HTTP server → API application: creates and serves (evidence: `backend-batch3.5/backend/src/server.ts`)
- API application → Authentication routes: mounts (evidence: `backend-batch3.5/backend/src/app.ts`)
- API application → Email API: mounts (evidence: `backend-batch3.5/backend/src/app.ts`)
- API application → Gmail API: mounts (evidence: `backend-batch3.5/backend/src/app.ts`)
- Email API → Session gate: protects routes (evidence: `backend-batch3.5/backend/src/routes/emails.ts`)
- Email API → Ingest pipeline: ingests email (evidence: `backend-batch3.5/backend/src/routes/emails.ts`)
- Email API → Email queries: queries records (evidence: `backend-batch3.5/backend/src/routes/emails.ts`)
- Email API → Email store: reads and writes (evidence: `backend-batch3.5/backend/src/routes/emails.ts`)
- Gmail API → Session gate: protects routes
- Ingest pipeline → Email parser: parses message (evidence: `backend-batch3.5/backend/src/services/emailIngestPipeline.ts`)
- Ingest pipeline → Header forensics: analyzes headers (evidence: `backend-batch3.5/backend/src/services/emailIngestPipeline.ts`)
- Ingest pipeline → Risk engine: computes risk (evidence: `backend-batch3.5/backend/src/services/emailIngestPipeline.ts`)
- Ingest pipeline → AI assessment: assesses with AI (evidence: `backend-batch3.5/backend/src/services/emailIngestPipeline.ts`)
- Ingest pipeline → Infrastructure analysis: checks infrastructure (evidence: `backend-batch3.5/backend/src/services/emailIngestPipeline.ts`)
- Ingest pipeline → Email store: stores evidence (evidence: `backend-batch3.5/backend/src/services/emailIngestPipeline.ts`)
- AI assessment → LLM provider client: uses provider (evidence: `backend-batch3.5/backend/src/analyzers/aiAssessment.ts`)
- Ingest pipeline → Domain schemas: builds typed record (evidence: `backend-batch3.5/backend/src/services/emailIngestPipeline.ts`)
- Email queries → Domain schemas: uses types (evidence: `backend-batch3.5/backend/src/services/emailQuery.ts`)