# aditya15128/phish-guard architecture

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

- Interactive diagram: https://gitdiagram.com/aditya15128/phish-guard
- Repository: https://github.com/aditya15128/phish-guard

## Overview

PhishGuard is a browser extension for manually scanning the active tab’s URL and presenting a phishing-risk verdict, scan totals, and recent history. The popup gets the active tab URL, sends a scan request to the background worker, and displays the returned result. The worker scores the URL with heuristic rules, updates local statistics and scan history, and serves statistics/reset requests. The content script and blocklist module are placeholders in the sampled source, so they are not shown as functioning detection stages.

Main entry points: [`background.js`](https://github.com/aditya15128/phish-guard/blob/main/background.js) (Background worker), [`popup/popup.js`](https://github.com/aditya15128/phish-guard/blob/main/popup/popup.js) (Popup UI), [`rules/heuristics.js`](https://github.com/aditya15128/phish-guard/blob/main/rules/heuristics.js) (Heuristic scoring)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Popup interface"]
  node_popup["Popup UI<br/>[popup.js]"]
end

subgraph group_scan["URL analysis"]
  node_worker["Background worker<br/>[background.js]"]
  node_heuristics["Heuristic scoring<br/>[heuristics.js]"]
end

subgraph group_state["Scan state"]
  node_storage[("Local extension storage")]
end

node_user(("Extension user"))
node_browser["Browser APIs"]

node_user -->|"requests scan"| node_popup
node_popup -->|"queries active tab"| node_browser
node_popup -->|"sends scan request"| node_worker
node_worker -->|"scores URL"| node_heuristics
node_worker -->|"updates scan state"| node_storage
node_storage -->|"returns stored state"| node_worker
node_popup -->|"reads scan history"| node_storage
node_worker -->|"returns verdict or stats"| node_popup
node_browser -->|"dispatches messages"| node_worker

click node_popup "https://github.com/aditya15128/phish-guard/blob/main/popup/popup.js"
click node_worker "https://github.com/aditya15128/phish-guard/blob/main/background.js"
click node_heuristics "https://github.com/aditya15128/phish-guard/blob/main/rules/heuristics.js"

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_user,node_browser toneBlue
class node_worker,node_heuristics toneAmber
class node_storage toneMint
```

## Components

### Popup interface

- [Popup UI](https://github.com/aditya15128/phish-guard/blob/main/popup/popup.js): `popup/popup.js`

### URL analysis

- [Background worker](https://github.com/aditya15128/phish-guard/blob/main/background.js): `background.js`
- [Heuristic scoring](https://github.com/aditya15128/phish-guard/blob/main/rules/heuristics.js): `rules/heuristics.js`

### Scan state

- **Local extension storage**

### Other components

- **Extension user**
- **Browser APIs**

## Connections

- Extension user → Popup UI: requests scan
- Popup UI → Browser APIs: queries active tab
- Popup UI → Background worker: sends scan request
- Background worker → Heuristic scoring: scores URL
- Background worker → Local extension storage: updates scan state
- Local extension storage → Background worker: returns stored state
- Popup UI → Local extension storage: reads scan history
- Background worker → Popup UI: returns verdict or stats
- Browser APIs → Background worker: dispatches messages