# valorz1/hookline architecture

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

- Interactive diagram: https://gitdiagram.com/valorz1/hookline
- Repository: https://github.com/valorz1/hookline

## Overview

HookLine analyzes suspicious emails through one shared pipeline: parse the message, extract observables, check for red flags, optionally query VirusTotal, then score the evidence into a verdict. Users can start that workflow from the terminal, a web upload, or a reporting inbox. The web app also streams VirusTotal progress to the result page. The README documents inbox OAuth and VT caching; sampled source shows the main analysis, web routes, and lookup implementation, but not the full inbox or browser UI internals.

Main entry points: [`analyser/pipeline.py`](https://github.com/valorz1/hookline/blob/main/analyser/pipeline.py) (Analysis orchestrator), [`app.py`](https://github.com/valorz1/hookline/blob/main/app.py) (Web upload), [`analyser/virustotal.py`](https://github.com/valorz1/hookline/blob/main/analyser/virustotal.py) (VirusTotal lookup), [`main.py`](https://github.com/valorz1/hookline/blob/main/main.py) (Terminal CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Email intake"]
  node_parser["Email parser<br/>[parser.py]"]
end

subgraph group_analysis["Analysis pipeline"]
  node_pipeline["Analysis orchestrator<br/>[pipeline.py]"]
  node_observables["Observable extraction<br/>[observables.py]"]
  node_checks["Red-flag checks<br/>[checks.py]"]
  node_verdict["Verdict scoring<br/>[verdict.py]"]
end

subgraph group_intel["Threat intelligence"]
  node_vt_targets["Lookup selection<br/>[virustotal.py]"]
  node_vt_lookup["VirusTotal lookup<br/>[virustotal.py]"]
  node_vt_cache[("Lookup cache<br/>[virustotal.py]")]
end

subgraph group_interfaces["User interfaces"]
  node_terminal["Terminal CLI<br/>[main.py]"]
  node_web["Web upload<br/>[app.py]"]
  node_web_templates["Web views"]
  node_web_client["Browser behavior<br/>[hookline.js]"]
  node_inbox["Inbox processor<br/>[inbox.py]"]
end

node_user(("Email submitter"))
node_mailbox[("Reporting mailbox")]
node_browser(("Browser user"))
node_virustotal["VirusTotal service"]

node_user -->|"runs analysis"| node_terminal
node_user -->|"uploads email"| node_web
node_user -->|"forwards report"| node_mailbox
node_browser -->|"submits email"| node_web
node_mailbox -->|"provides reports"| node_inbox
node_terminal -->|"reads email"| node_parser
node_terminal -->|"runs analysis"| node_pipeline
node_web -->|"parses upload"| node_parser
node_web -->|"runs quick checks"| node_pipeline
node_web -->|"selects targets"| node_vt_targets
node_web -->|"renders views"| node_web_templates
node_web_client -->|"receives live events"| node_web
node_inbox -->|"parses attachment"| node_parser
node_inbox -->|"runs analysis"| node_pipeline
node_pipeline -->|"extracts evidence"| node_observables
node_pipeline -->|"runs checks"| node_checks
node_checks -->|"uses URL helpers"| node_observables
node_pipeline -->|"selects lookups"| node_vt_targets
node_pipeline -->|"queries targets"| node_vt_lookup
node_pipeline -->|"scores findings"| node_verdict
node_verdict -->|"formats findings"| node_checks
node_vt_lookup -->|"reads and writes"| node_vt_cache
node_vt_lookup -->|"requests intelligence"| node_virustotal

click node_terminal "https://github.com/valorz1/hookline/blob/main/main.py"
click node_web "https://github.com/valorz1/hookline/blob/main/app.py"
click node_web_templates "https://github.com/valorz1/hookline/tree/main/templates"
click node_web_client "https://github.com/valorz1/hookline/blob/main/static/hookline.js"
click node_inbox "https://github.com/valorz1/hookline/blob/main/inbox.py"
click node_parser "https://github.com/valorz1/hookline/blob/main/analyser/parser.py"
click node_pipeline "https://github.com/valorz1/hookline/blob/main/analyser/pipeline.py"
click node_observables "https://github.com/valorz1/hookline/blob/main/analyser/observables.py"
click node_checks "https://github.com/valorz1/hookline/blob/main/analyser/checks.py"
click node_verdict "https://github.com/valorz1/hookline/blob/main/analyser/verdict.py"
click node_vt_targets "https://github.com/valorz1/hookline/blob/main/analyser/virustotal.py"
click node_vt_lookup "https://github.com/valorz1/hookline/blob/main/analyser/virustotal.py"
click node_vt_cache "https://github.com/valorz1/hookline/blob/main/analyser/virustotal.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_parser,node_browser toneBlue
class node_pipeline,node_observables,node_checks,node_verdict,node_mailbox toneAmber
class node_vt_targets,node_vt_lookup,node_vt_cache toneMint
class node_terminal,node_web,node_web_templates,node_web_client,node_inbox toneRose
class node_user,node_virustotal toneIndigo
```

## Components

### Email intake

- [Email parser](https://github.com/valorz1/hookline/blob/main/analyser/parser.py): `analyser/parser.py`

### Analysis pipeline

- [Analysis orchestrator](https://github.com/valorz1/hookline/blob/main/analyser/pipeline.py): `analyser/pipeline.py`
- [Observable extraction](https://github.com/valorz1/hookline/blob/main/analyser/observables.py): `analyser/observables.py`
- [Red-flag checks](https://github.com/valorz1/hookline/blob/main/analyser/checks.py): `analyser/checks.py`
- [Verdict scoring](https://github.com/valorz1/hookline/blob/main/analyser/verdict.py): `analyser/verdict.py`

### Threat intelligence

- [Lookup selection](https://github.com/valorz1/hookline/blob/main/analyser/virustotal.py): `analyser/virustotal.py`
- [VirusTotal lookup](https://github.com/valorz1/hookline/blob/main/analyser/virustotal.py): `analyser/virustotal.py`
- [Lookup cache](https://github.com/valorz1/hookline/blob/main/analyser/virustotal.py): `analyser/virustotal.py`

### User interfaces

- [Terminal CLI](https://github.com/valorz1/hookline/blob/main/main.py): `main.py`
- [Web upload](https://github.com/valorz1/hookline/blob/main/app.py): `app.py`
- [Web views](https://github.com/valorz1/hookline/tree/main/templates): `templates`
- [Browser behavior](https://github.com/valorz1/hookline/blob/main/static/hookline.js): `static/hookline.js`
- [Inbox processor](https://github.com/valorz1/hookline/blob/main/inbox.py): `inbox.py`

### Other components

- **Email submitter**
- **Reporting mailbox**
- **Browser user**
- **VirusTotal service**

## Connections

- Email submitter → Terminal CLI: runs analysis (evidence: `README.md`)
- Email submitter → Web upload: uploads email (evidence: `README.md`)
- Email submitter → Reporting mailbox: forwards report (evidence: `README.md`)
- Browser user → Web upload: submits email (evidence: `README.md`)
- Reporting mailbox → Inbox processor: provides reports (evidence: `inbox.py`)
- Terminal CLI → Email parser: reads email (evidence: `main.py`)
- Terminal CLI → Analysis orchestrator: runs analysis (evidence: `main.py`)
- Web upload → Email parser: parses upload (evidence: `app.py`)
- Web upload → Analysis orchestrator: runs quick checks (evidence: `app.py`)
- Web upload → Lookup selection: selects targets (evidence: `app.py`)
- Web upload → Web views: renders views (evidence: `app.py`)
- Browser behavior → Web upload: receives live events (evidence: `static/hookline.js`)
- Inbox processor → Email parser: parses attachment (evidence: `inbox.py`)
- Inbox processor → Analysis orchestrator: runs analysis (evidence: `inbox.py`)
- Analysis orchestrator → Observable extraction: extracts evidence (evidence: `analyser/pipeline.py`)
- Analysis orchestrator → Red-flag checks: runs checks (evidence: `analyser/pipeline.py`)
- Red-flag checks → Observable extraction: uses URL helpers (evidence: `analyser/checks.py`)
- Analysis orchestrator → Lookup selection: selects lookups (evidence: `analyser/pipeline.py`)
- Analysis orchestrator → VirusTotal lookup: queries targets (evidence: `analyser/pipeline.py`)
- Analysis orchestrator → Verdict scoring: scores findings (evidence: `analyser/pipeline.py`)
- Verdict scoring → Red-flag checks: formats findings (evidence: `analyser/verdict.py`)
- VirusTotal lookup → Lookup cache: reads and writes (evidence: `README.md`)
- VirusTotal lookup → VirusTotal service: requests intelligence (evidence: `analyser/virustotal.py`)
