# anzouk/phishlens architecture

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

- Interactive diagram: https://gitdiagram.com/anzouk/phishlens
- Repository: https://github.com/anzouk/phishlens

## Overview

PhishLens is a browser extension and server that analyzes email and attachments, then presents a verdict and reasons. The principal flow is a user-initiated Gmail or Outlook scan, proxied by the extension to the backend, which parses the message, runs text, URL and sender checks, fuses results, and returns an explanation. Attachment scanning, history, and optional wrong-verdict reporting are distinct product capabilities. Arrows are limited to README statements and the shown backend call/reference evidence; unsampled implementation links are omitted.

Main entry points: [`backend/extension_backend.py`](https://github.com/anzouk/phishlens/blob/main/backend/extension_backend.py) (API orchestration), [`extension/background.js`](https://github.com/anzouk/phishlens/blob/main/extension/background.js) (Request proxy), [`backend/attachment_analysis.py`](https://github.com/anzouk/phishlens/blob/main/backend/attachment_analysis.py) (Attachment analysis), [`extension/content_scripts/gmail_scan.js`](https://github.com/anzouk/phishlens/blob/main/extension/content_scripts/gmail_scan.js) (Mail scanning)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_extension["Mail extension"]
  node_popup["Popup scans<br/>[popup.js]"]
  node_mail_scan["Mail scanning<br/>[gmail_scan.js]"]
  node_attachments_ui["Attachment scans<br/>[attachments.js]"]
  node_background["Request proxy<br/>[background.js]"]
end

subgraph group_backend["Analysis backend"]
  node_api["API orchestration"]
  node_email_parse["Email parsing<br/>[email_parsing.py]"]
  node_fusion["Verdict fusion<br/>[fusion.py]"]
  node_cache[("Result cache<br/>[result_cache.py]")]
end

subgraph group_agents["Detection signals"]
  node_text["Text model<br/>[text_model.py]"]
  node_structured["URL and metadata agents"]
  node_sender["Sender trust<br/>[sender_trust.py]"]
  node_headers["Auth headers<br/>[auth_headers.py]"]
  node_reputation["URL reputation<br/>[reputation.py]"]
  node_features["Feature extraction"]
end

subgraph group_attachments["Attachment inspection"]
  node_attachment_analysis["Attachment analysis"]
  node_archive["Archive analysis"]
  node_office["Office analysis<br/>[office_analysis.py]"]
  node_ocr["OCR and QR<br/>[ocr.py]"]
end

subgraph group_state["History and feedback"]
  node_history[("Local scan history<br/>[history.js]")]
  node_feedback["Verdict reporting<br/>[feedback.py]"]
end

node_user(("Email user"))
node_mail["Gmail / Outlook"]
node_intel["Threat-intelligence feeds"]

node_user -->|"starts scan"| node_mail_scan
node_mail -->|"provides email"| node_mail_scan
node_user -->|"submits content"| node_popup
node_mail_scan -->|"requests analysis"| node_background
node_popup -->|"requests analysis"| node_background
node_attachments_ui -->|"requests scan"| node_background
node_background -->|"proxies API calls"| node_api
node_api -->|"parses email"| node_email_parse
node_api -->|"scores text"| node_text
node_api -->|"scores links and metadata"| node_structured
node_api -->|"checks sender"| node_sender
node_api -->|"checks headers"| node_headers
node_api -->|"checks URLs"| node_reputation
node_api -->|"combines scores"| node_fusion
node_api -->|"reads and writes"| node_cache
node_api -->|"analyzes attachments"| node_attachment_analysis
node_attachment_analysis -->|"dispatches archives"| node_archive
node_attachment_analysis -->|"analyzes Office files"| node_office
node_attachment_analysis -->|"scans images and PDFs"| node_ocr
node_reputation -->|"queries feeds"| node_intel
node_background -->|"saves scan history"| node_history
node_user -->|"reports verdict"| node_feedback

click node_popup "https://github.com/anzouk/phishlens/blob/main/extension/popup/popup.js"
click node_mail_scan "https://github.com/anzouk/phishlens/blob/main/extension/content_scripts/gmail_scan.js"
click node_attachments_ui "https://github.com/anzouk/phishlens/blob/main/extension/content_scripts/attachments.js"
click node_background "https://github.com/anzouk/phishlens/blob/main/extension/background.js"
click node_api "https://github.com/anzouk/phishlens/blob/main/backend/extension_backend.py"
click node_email_parse "https://github.com/anzouk/phishlens/blob/main/backend/email_parsing.py"
click node_fusion "https://github.com/anzouk/phishlens/blob/main/backend/fusion.py"
click node_cache "https://github.com/anzouk/phishlens/blob/main/backend/result_cache.py"
click node_text "https://github.com/anzouk/phishlens/blob/main/backend/text_model.py"
click node_structured "https://github.com/anzouk/phishlens/blob/main/backend/structured_agents.py"
click node_sender "https://github.com/anzouk/phishlens/blob/main/backend/sender_trust.py"
click node_headers "https://github.com/anzouk/phishlens/blob/main/backend/auth_headers.py"
click node_reputation "https://github.com/anzouk/phishlens/blob/main/backend/reputation.py"
click node_features "https://github.com/anzouk/phishlens/blob/main/backend/feature_extraction.py"
click node_attachment_analysis "https://github.com/anzouk/phishlens/blob/main/backend/attachment_analysis.py"
click node_archive "https://github.com/anzouk/phishlens/blob/main/backend/archive_analysis.py"
click node_office "https://github.com/anzouk/phishlens/blob/main/backend/office_analysis.py"
click node_ocr "https://github.com/anzouk/phishlens/blob/main/backend/ocr.py"
click node_history "https://github.com/anzouk/phishlens/blob/main/extension/lib/history.js"
click node_feedback "https://github.com/anzouk/phishlens/blob/main/backend/feedback.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_popup,node_mail_scan,node_attachments_ui,node_background,node_user toneBlue
class node_api,node_email_parse,node_fusion,node_cache toneAmber
class node_text,node_structured,node_sender,node_headers,node_reputation,node_features toneMint
class node_attachment_analysis,node_archive,node_office,node_ocr toneRose
class node_history,node_feedback,node_mail,node_intel toneIndigo
```

## Components

### Mail extension

- [Popup scans](https://github.com/anzouk/phishlens/blob/main/extension/popup/popup.js): `extension/popup/popup.js`
- [Mail scanning](https://github.com/anzouk/phishlens/blob/main/extension/content_scripts/gmail_scan.js): `extension/content_scripts/gmail_scan.js`
- [Attachment scans](https://github.com/anzouk/phishlens/blob/main/extension/content_scripts/attachments.js): `extension/content_scripts/attachments.js`
- [Request proxy](https://github.com/anzouk/phishlens/blob/main/extension/background.js): `extension/background.js`

### Analysis backend

- [API orchestration](https://github.com/anzouk/phishlens/blob/main/backend/extension_backend.py): `backend/extension_backend.py`
- [Email parsing](https://github.com/anzouk/phishlens/blob/main/backend/email_parsing.py): `backend/email_parsing.py`
- [Verdict fusion](https://github.com/anzouk/phishlens/blob/main/backend/fusion.py): `backend/fusion.py`
- [Result cache](https://github.com/anzouk/phishlens/blob/main/backend/result_cache.py): `backend/result_cache.py`

### Detection signals

- [Text model](https://github.com/anzouk/phishlens/blob/main/backend/text_model.py): `backend/text_model.py`
- [URL and metadata agents](https://github.com/anzouk/phishlens/blob/main/backend/structured_agents.py): `backend/structured_agents.py`
- [Sender trust](https://github.com/anzouk/phishlens/blob/main/backend/sender_trust.py): `backend/sender_trust.py`
- [Auth headers](https://github.com/anzouk/phishlens/blob/main/backend/auth_headers.py): `backend/auth_headers.py`
- [URL reputation](https://github.com/anzouk/phishlens/blob/main/backend/reputation.py): `backend/reputation.py`
- [Feature extraction](https://github.com/anzouk/phishlens/blob/main/backend/feature_extraction.py): `backend/feature_extraction.py`

### Attachment inspection

- [Attachment analysis](https://github.com/anzouk/phishlens/blob/main/backend/attachment_analysis.py): `backend/attachment_analysis.py`
- [Archive analysis](https://github.com/anzouk/phishlens/blob/main/backend/archive_analysis.py): `backend/archive_analysis.py`
- [Office analysis](https://github.com/anzouk/phishlens/blob/main/backend/office_analysis.py): `backend/office_analysis.py`
- [OCR and QR](https://github.com/anzouk/phishlens/blob/main/backend/ocr.py): `backend/ocr.py`

### History and feedback

- [Local scan history](https://github.com/anzouk/phishlens/blob/main/extension/lib/history.js): `extension/lib/history.js`
- [Verdict reporting](https://github.com/anzouk/phishlens/blob/main/backend/feedback.py): `backend/feedback.py`

### Other components

- **Email user**
- **Gmail / Outlook**
- **Threat-intelligence feeds**

## Connections

- Email user → Mail scanning: starts scan (evidence: `README.md`)
- Gmail / Outlook → Mail scanning: provides email (evidence: `README.md`)
- Email user → Popup scans: submits content (evidence: `README.md`)
- Mail scanning → Request proxy: requests analysis (evidence: `extension/background.js`)
- Popup scans → Request proxy: requests analysis (evidence: `README.md`)
- Attachment scans → Request proxy: requests scan (evidence: `extension/background.js`)
- Request proxy → API orchestration: proxies API calls (evidence: `extension/background.js`)
- API orchestration → Email parsing: parses email (evidence: `backend/extension_backend.py`)
- API orchestration → Text model: scores text (evidence: `backend/extension_backend.py`)
- API orchestration → URL and metadata agents: scores links and metadata (evidence: `backend/extension_backend.py`)
- API orchestration → Sender trust: checks sender (evidence: `backend/extension_backend.py`)
- API orchestration → Auth headers: checks headers (evidence: `backend/extension_backend.py`)
- API orchestration → URL reputation: checks URLs (evidence: `backend/extension_backend.py`)
- API orchestration → Verdict fusion: combines scores (evidence: `backend/extension_backend.py`)
- API orchestration → Result cache: reads and writes (evidence: `backend/extension_backend.py`)
- API orchestration → Attachment analysis: analyzes attachments (evidence: `backend/extension_backend.py`)
- Attachment analysis → Archive analysis: dispatches archives (evidence: `backend/attachment_analysis.py`)
- Attachment analysis → Office analysis: analyzes Office files (evidence: `backend/attachment_analysis.py`)
- Attachment analysis → OCR and QR: scans images and PDFs (evidence: `backend/attachment_analysis.py`)
- URL reputation → Threat-intelligence feeds: queries feeds (evidence: `README.md`)
- Request proxy → Local scan history: saves scan history (evidence: `extension/background.js`)
- Email user → Verdict reporting: reports verdict (evidence: `README.md`)
