# th-shivam/phishguard architecture

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

- Interactive diagram: https://gitdiagram.com/th-shivam/phishguard
- Repository: https://github.com/th-shivam/phishguard

## Overview

PHISHGUARD is a browser extension whose main workflow monitors page navigations, submits URLs to VirusTotal, and redirects flagged pages to a warning screen after adding a blocking rule. The popup separately reads and changes the protection setting. The README also describes community reporting and color-coded warnings; the sampled warning-page code implements a local report alert rather than showing a network submission. Connections are limited to the README and sampled source; other files in the tree were not inspected.

Main entry points: [`background.js`](https://github.com/th-shivam/phishguard/blob/main/background.js) (Navigation Monitor), [`blocked.html`](https://github.com/th-shivam/phishguard/blob/main/blocked.html) (Warning Page), [`popup/popup.html`](https://github.com/th-shivam/phishguard/blob/main/popup/popup.html) (Protection Popup), [`popup/popup.js`](https://github.com/th-shivam/phishguard/blob/main/popup/popup.js) (Popup Controls)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_protection["Threat Protection"]
  node_navigation["Navigation Monitor<br/>[background.js]"]
  node_url_scan["URL Scanner<br/>[background.js]"]
  node_rule_block["Dynamic Rule Blocking<br/>[background.js]"]
end

subgraph group_interface["User Interfaces"]
  node_warning_page["Warning Page<br/>[blocked.html]"]
  node_warning_logic["Warning Interactions<br/>[blocked.js]"]
  node_popup["Protection Popup<br/>[popup.html]"]
  node_popup_logic["Popup Controls<br/>[popup.js]"]
end

subgraph group_browser["Browser Services"]
  node_virustotal{{"VirusTotal"}}
  node_browser_rules["Browser Rule Engine"]
  node_protection_state[("Protection Setting")]
end

node_browser_user(("Browser User"))

node_browser_user -->|"navigates"| node_navigation
node_navigation -->|"reads setting"| node_protection_state
node_navigation -->|"submits URL"| node_url_scan
node_url_scan -->|"scans URL"| node_virustotal
node_navigation -->|"blocks flagged URL"| node_rule_block
node_rule_block -->|"adds rule"| node_browser_rules
node_navigation -->|"redirects flagged tab"| node_warning_page
node_warning_page -.->|"loads behavior"| node_warning_logic
node_browser_user -->|"opens"| node_popup
node_popup -.->|"loads controls"| node_popup_logic
node_popup_logic -->|"reads and writes"| node_protection_state
node_browser_user -->|"chooses warning action"| node_warning_logic

click node_navigation "https://github.com/th-shivam/phishguard/blob/main/background.js"
click node_url_scan "https://github.com/th-shivam/phishguard/blob/main/background.js"
click node_rule_block "https://github.com/th-shivam/phishguard/blob/main/background.js"
click node_warning_page "https://github.com/th-shivam/phishguard/blob/main/blocked.html"
click node_warning_logic "https://github.com/th-shivam/phishguard/blob/main/static/js/blocked.js"
click node_popup "https://github.com/th-shivam/phishguard/blob/main/popup/popup.html"
click node_popup_logic "https://github.com/th-shivam/phishguard/blob/main/popup/popup.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_navigation,node_url_scan,node_rule_block,node_browser_user toneBlue
class node_warning_page,node_warning_logic,node_popup,node_popup_logic toneAmber
class node_virustotal,node_browser_rules,node_protection_state toneMint
```

## Components

### Threat Protection

- [Navigation Monitor](https://github.com/th-shivam/phishguard/blob/main/background.js): `background.js`
- [URL Scanner](https://github.com/th-shivam/phishguard/blob/main/background.js): `background.js`
- [Dynamic Rule Blocking](https://github.com/th-shivam/phishguard/blob/main/background.js): `background.js`

### User Interfaces

- [Warning Page](https://github.com/th-shivam/phishguard/blob/main/blocked.html): `blocked.html`
- [Warning Interactions](https://github.com/th-shivam/phishguard/blob/main/static/js/blocked.js): `static/js/blocked.js`
- [Protection Popup](https://github.com/th-shivam/phishguard/blob/main/popup/popup.html): `popup/popup.html`
- [Popup Controls](https://github.com/th-shivam/phishguard/blob/main/popup/popup.js): `popup/popup.js`

### Browser Services

- **VirusTotal**
- **Browser Rule Engine**
- **Protection Setting**

### Other components

- **Browser User**

## Connections

- Browser User → Navigation Monitor: navigates (evidence: `README.md`)
- Navigation Monitor → Protection Setting: reads setting (evidence: `background.js`)
- Navigation Monitor → URL Scanner: submits URL (evidence: `background.js`)
- URL Scanner → VirusTotal: scans URL (evidence: `background.js`)
- Navigation Monitor → Dynamic Rule Blocking: blocks flagged URL (evidence: `background.js`)
- Dynamic Rule Blocking → Browser Rule Engine: adds rule (evidence: `background.js`)
- Navigation Monitor → Warning Page: redirects flagged tab (evidence: `background.js`)
- Warning Page → Warning Interactions: loads behavior
- Browser User → Protection Popup: opens (evidence: `README.md`)
- Protection Popup → Popup Controls: loads controls
- Popup Controls → Protection Setting: reads and writes (evidence: `popup/popup.js`)
- Browser User → Warning Interactions: chooses warning action (evidence: `static/js/blocked.js`)
