# hussein-design/phish-analyzer architecture

> Architecture diagram of the GitHub repository hussein-design/phish-analyzer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hussein-design/phish-analyzer
- Repository: https://github.com/hussein-design/phish-analyzer

## Overview

Phish Analyzer Desktop is a local desktop application for turning suspicious .eml files into explainable phishing verdicts and reports. A user uploads a message through the PySide interface; the local API validates and records it, then analysis parses email evidence, evaluates header/body/URL/attachment signals, optionally enriches indicators with threat-intelligence providers, scores the evidence, and persists results for history, detail views, and DOCX export. The graph preserves these documented capabilities; several backend internals are represented at directory level because their source was not sampled.

Main entry points: [`backend/services/analysis_service.py`](https://github.com/hussein-design/phish-analyzer/blob/main/backend/services/analysis_service.py) (Analysis orchestration), [`backend/routes/analyses.py`](https://github.com/hussein-design/phish-analyzer/blob/main/backend/routes/analyses.py) (FastAPI routes), [`frontend/services/api_client.py`](https://github.com/hussein-design/phish-analyzer/blob/main/frontend/services/api_client.py) (API client), [`frontend/views/main_window.py`](https://github.com/hussein-design/phish-analyzer/blob/main/frontend/views/main_window.py) (Main window)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop UI"]
  node_window["Main window<br/>[main_window.py]"]
  node_upload["Upload page<br/>[upload_page.py]"]
  node_uploadctl["Upload controller"]
  node_historyctl["History controller"]
  node_reportctl["Report controller"]
  node_settingsctl["Settings controller"]
  node_client["API client<br/>[api_client.py]"]
  node_reportview["Report page<br/>[report_page.py]"]
end

subgraph group_api["Local API"]
  node_backend["FastAPI routes<br/>[analyses.py]"]
  node_settingsroute["Settings routes<br/>[settings.py]"]
end

subgraph group_analysis["Analysis pipeline"]
  node_validation["Upload validation"]
  node_analysis_service["Analysis orchestration"]
  node_parser["Email parser"]
  node_signals["Threat signals<br/>[threat_signals.py]"]
  node_urlintel["URL analysis"]
  node_attachment["Attachment analysis"]
  node_scoring["Scoring and verdict<br/>[scoring_service.py]"]
  node_report["DOCX reporting<br/>[report_service.py]"]
end

subgraph group_state["Persistence and settings"]
  node_repo["Analysis repository"]
  node_db[("SQLite database<br/>[session.py]")]
  node_settingsrepo["Settings repository"]
  node_settingsmodel["Settings model<br/>[app_settings.py]"]
end

subgraph group_intel["Threat intelligence"]
  node_vt["VirusTotal provider"]
  node_abuse["AbuseIPDB provider"]
  node_shodan["Shodan provider<br/>[shodan_provider.py]"]
  node_sandbox["Sandbox provider"]
end

node_user(("Desktop user"))
node_vtservice(("VirusTotal"))
node_abuseservice(("AbuseIPDB"))
node_shodanservice(("Shodan"))
node_sandboxservice(("Sandbox service"))

node_user -->|"selects email"| node_upload
node_window -->|"connects UI"| node_uploadctl
node_window -->|"connects UI"| node_historyctl
node_window -->|"connects UI"| node_reportctl
node_window -->|"connects UI"| node_settingsctl
node_upload -->|"emits file"| node_uploadctl
node_uploadctl -->|"uploads email"| node_client
node_historyctl -->|"requests history"| node_client
node_reportctl -->|"requests detail"| node_client
node_settingsctl -->|"reads and saves"| node_client
node_client -->|"HTTP requests"| node_backend
node_backend -->|"validates upload"| node_validation
node_backend -->|"starts analysis"| node_analysis_service
node_analysis_service -->|"parses message"| node_parser
node_analysis_service -->|"evaluates indicators"| node_signals
node_analysis_service -->|"analyzes URLs"| node_urlintel
node_analysis_service -->|"inspects files"| node_attachment
node_analysis_service -->|"scores signals"| node_scoring
node_analysis_service -.->|"requests enrichment"| node_vt
node_analysis_service -.->|"requests enrichment"| node_abuse
node_analysis_service -.->|"requests enrichment"| node_shodan
node_analysis_service -.->|"requests enrichment"| node_sandbox
node_vt -.->|"queries reputation"| node_vtservice
node_abuse -.->|"queries reputation"| node_abuseservice
node_shodan -.->|"queries IP intel"| node_shodanservice
node_sandbox -.->|"submits sample"| node_sandboxservice
node_analysis_service -->|"persists result"| node_repo
node_repo -->|"reads and writes"| node_db
node_backend -->|"queries analyses"| node_repo
node_backend -->|"builds report"| node_report
node_report -->|"loads analysis"| node_repo
node_backend -->|"loads and saves"| node_settingsrepo
node_settingsroute -->|"loads and saves"| node_settingsrepo
node_settingsrepo -->|"reads and writes"| node_db
node_settingsrepo -->|"persists settings"| node_settingsmodel
node_backend -->|"routes settings"| node_settingsroute
node_reportctl -->|"displays results"| node_reportview
node_client -->|"returns response"| node_reportctl

click node_window "https://github.com/hussein-design/phish-analyzer/blob/main/frontend/views/main_window.py"
click node_upload "https://github.com/hussein-design/phish-analyzer/blob/main/frontend/views/upload_page.py"
click node_uploadctl "https://github.com/hussein-design/phish-analyzer/blob/main/frontend/controllers/upload_controller.py"
click node_historyctl "https://github.com/hussein-design/phish-analyzer/blob/main/frontend/controllers/analyses_controller.py"
click node_reportctl "https://github.com/hussein-design/phish-analyzer/blob/main/frontend/controllers/report_controller.py"
click node_settingsctl "https://github.com/hussein-design/phish-analyzer/blob/main/frontend/controllers/settings_controller.py"
click node_client "https://github.com/hussein-design/phish-analyzer/blob/main/frontend/services/api_client.py"
click node_reportview "https://github.com/hussein-design/phish-analyzer/blob/main/frontend/views/report_page.py"
click node_backend "https://github.com/hussein-design/phish-analyzer/blob/main/backend/routes/analyses.py"
click node_settingsroute "https://github.com/hussein-design/phish-analyzer/blob/main/backend/routes/settings.py"
click node_validation "https://github.com/hussein-design/phish-analyzer/blob/main/backend/services/validation_service.py"
click node_analysis_service "https://github.com/hussein-design/phish-analyzer/blob/main/backend/services/analysis_service.py"
click node_parser "https://github.com/hussein-design/phish-analyzer/blob/main/backend/services/eml_parser_service.py"
click node_signals "https://github.com/hussein-design/phish-analyzer/blob/main/backend/services/threat_signals.py"
click node_urlintel "https://github.com/hussein-design/phish-analyzer/blob/main/backend/services/url_intelligence_service.py"
click node_attachment "https://github.com/hussein-design/phish-analyzer/blob/main/backend/services/attachment_intelligence_service.py"
click node_scoring "https://github.com/hussein-design/phish-analyzer/blob/main/backend/services/scoring_service.py"
click node_report "https://github.com/hussein-design/phish-analyzer/blob/main/backend/services/report_service.py"
click node_repo "https://github.com/hussein-design/phish-analyzer/blob/main/backend/repositories/analysis_repository.py"
click node_db "https://github.com/hussein-design/phish-analyzer/blob/main/backend/database/session.py"
click node_settingsrepo "https://github.com/hussein-design/phish-analyzer/blob/main/backend/repositories/settings_repository.py"
click node_settingsmodel "https://github.com/hussein-design/phish-analyzer/blob/main/backend/models/app_settings.py"
click node_vt "https://github.com/hussein-design/phish-analyzer/blob/main/backend/services/enrichment/virustotal_provider.py"
click node_abuse "https://github.com/hussein-design/phish-analyzer/blob/main/backend/services/enrichment/abuseipdb_provider.py"
click node_shodan "https://github.com/hussein-design/phish-analyzer/blob/main/backend/services/enrichment/shodan_provider.py"
click node_sandbox "https://github.com/hussein-design/phish-analyzer/blob/main/backend/services/enrichment/sandbox_provider.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_window,node_upload,node_uploadctl,node_historyctl,node_reportctl,node_settingsctl,node_client,node_reportview,node_user toneBlue
class node_backend,node_settingsroute toneAmber
class node_validation,node_analysis_service,node_parser,node_signals,node_urlintel,node_attachment,node_scoring,node_report toneMint
class node_repo,node_db,node_settingsrepo,node_settingsmodel toneRose
class node_vt,node_abuse,node_shodan,node_sandbox,node_vtservice,node_abuseservice,node_shodanservice,node_sandboxservice toneIndigo
```

## Components

### Desktop UI

- [Main window](https://github.com/hussein-design/phish-analyzer/blob/main/frontend/views/main_window.py): `frontend/views/main_window.py`
- [Upload page](https://github.com/hussein-design/phish-analyzer/blob/main/frontend/views/upload_page.py): `frontend/views/upload_page.py`
- [Upload controller](https://github.com/hussein-design/phish-analyzer/blob/main/frontend/controllers/upload_controller.py): `frontend/controllers/upload_controller.py`
- [History controller](https://github.com/hussein-design/phish-analyzer/blob/main/frontend/controllers/analyses_controller.py): `frontend/controllers/analyses_controller.py`
- [Report controller](https://github.com/hussein-design/phish-analyzer/blob/main/frontend/controllers/report_controller.py): `frontend/controllers/report_controller.py`
- [Settings controller](https://github.com/hussein-design/phish-analyzer/blob/main/frontend/controllers/settings_controller.py): `frontend/controllers/settings_controller.py`
- [API client](https://github.com/hussein-design/phish-analyzer/blob/main/frontend/services/api_client.py): `frontend/services/api_client.py`
- [Report page](https://github.com/hussein-design/phish-analyzer/blob/main/frontend/views/report_page.py): `frontend/views/report_page.py`

### Local API

- [FastAPI routes](https://github.com/hussein-design/phish-analyzer/blob/main/backend/routes/analyses.py): `backend/routes/analyses.py`
- [Settings routes](https://github.com/hussein-design/phish-analyzer/blob/main/backend/routes/settings.py): `backend/routes/settings.py`

### Analysis pipeline

- [Upload validation](https://github.com/hussein-design/phish-analyzer/blob/main/backend/services/validation_service.py): `backend/services/validation_service.py`
- [Analysis orchestration](https://github.com/hussein-design/phish-analyzer/blob/main/backend/services/analysis_service.py): `backend/services/analysis_service.py`
- [Email parser](https://github.com/hussein-design/phish-analyzer/blob/main/backend/services/eml_parser_service.py): `backend/services/eml_parser_service.py`
- [Threat signals](https://github.com/hussein-design/phish-analyzer/blob/main/backend/services/threat_signals.py): `backend/services/threat_signals.py`
- [URL analysis](https://github.com/hussein-design/phish-analyzer/blob/main/backend/services/url_intelligence_service.py): `backend/services/url_intelligence_service.py`
- [Attachment analysis](https://github.com/hussein-design/phish-analyzer/blob/main/backend/services/attachment_intelligence_service.py): `backend/services/attachment_intelligence_service.py`
- [Scoring and verdict](https://github.com/hussein-design/phish-analyzer/blob/main/backend/services/scoring_service.py): `backend/services/scoring_service.py`
- [DOCX reporting](https://github.com/hussein-design/phish-analyzer/blob/main/backend/services/report_service.py): `backend/services/report_service.py`

### Persistence and settings

- [Analysis repository](https://github.com/hussein-design/phish-analyzer/blob/main/backend/repositories/analysis_repository.py): `backend/repositories/analysis_repository.py`
- [SQLite database](https://github.com/hussein-design/phish-analyzer/blob/main/backend/database/session.py): `backend/database/session.py`
- [Settings repository](https://github.com/hussein-design/phish-analyzer/blob/main/backend/repositories/settings_repository.py): `backend/repositories/settings_repository.py`
- [Settings model](https://github.com/hussein-design/phish-analyzer/blob/main/backend/models/app_settings.py): `backend/models/app_settings.py`

### Threat intelligence

- [VirusTotal provider](https://github.com/hussein-design/phish-analyzer/blob/main/backend/services/enrichment/virustotal_provider.py): `backend/services/enrichment/virustotal_provider.py`
- [AbuseIPDB provider](https://github.com/hussein-design/phish-analyzer/blob/main/backend/services/enrichment/abuseipdb_provider.py): `backend/services/enrichment/abuseipdb_provider.py`
- [Shodan provider](https://github.com/hussein-design/phish-analyzer/blob/main/backend/services/enrichment/shodan_provider.py): `backend/services/enrichment/shodan_provider.py`
- [Sandbox provider](https://github.com/hussein-design/phish-analyzer/blob/main/backend/services/enrichment/sandbox_provider.py): `backend/services/enrichment/sandbox_provider.py`

### Other components

- **Desktop user**
- **VirusTotal**
- **AbuseIPDB**
- **Shodan**
- **Sandbox service**

## Connections

- Desktop user → Upload page: selects email
- Main window → Upload controller: connects UI
- Main window → History controller: connects UI
- Main window → Report controller: connects UI
- Main window → Settings controller: connects UI
- Upload page → Upload controller: emits file
- Upload controller → API client: uploads email
- History controller → API client: requests history
- Report controller → API client: requests detail
- Settings controller → API client: reads and saves
- API client → FastAPI routes: HTTP requests
- FastAPI routes → Upload validation: validates upload
- FastAPI routes → Analysis orchestration: starts analysis
- Analysis orchestration → Email parser: parses message
- Analysis orchestration → Threat signals: evaluates indicators
- Analysis orchestration → URL analysis: analyzes URLs
- Analysis orchestration → Attachment analysis: inspects files
- Analysis orchestration → Scoring and verdict: scores signals
- Analysis orchestration → VirusTotal provider: requests enrichment
- Analysis orchestration → AbuseIPDB provider: requests enrichment
- Analysis orchestration → Shodan provider: requests enrichment
- Analysis orchestration → Sandbox provider: requests enrichment
- VirusTotal provider → VirusTotal: queries reputation
- AbuseIPDB provider → AbuseIPDB: queries reputation
- Shodan provider → Shodan: queries IP intel
- Sandbox provider → Sandbox service: submits sample
- Analysis orchestration → Analysis repository: persists result
- Analysis repository → SQLite database: reads and writes
- FastAPI routes → Analysis repository: queries analyses
- FastAPI routes → DOCX reporting: builds report
- DOCX reporting → Analysis repository: loads analysis
- FastAPI routes → Settings repository: loads and saves
- Settings routes → Settings repository: loads and saves
- Settings repository → SQLite database: reads and writes
- Settings repository → Settings model: persists settings
- FastAPI routes → Settings routes: routes settings
- Report controller → Report page: displays results
- API client → Report controller: returns response