# bkg10/phishshield_extension architecture

> Architecture diagram of the GitHub repository bkg10/phishshield_extension, 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/bkg10/phishshield_extension
- Repository: https://github.com/bkg10/phishshield_extension

## Overview

PhishShield is a Chrome extension backed by a FastAPI phishing classifier. Its main workflow watches page navigation, sends the URL for analysis, and presents a verdict in-page and in the popup. The backend extracts page/URL signals and classifies them with a scaler and XGBoost model; the extension also reuses recent same-domain scans and keeps local history. The graph reflects documented and excerpted wiring; popup HTML, manifest permissions, and model internals were not sampled.

Main entry points: [`Frontend/background.js`](https://github.com/bkg10/phishshield_extension/blob/main/Frontend/background.js) (Scan orchestration), [`backend/app.py`](https://github.com/bkg10/phishshield_extension/blob/main/backend/app.py) (Prediction API), [`Frontend/popup.js`](https://github.com/bkg10/phishshield_extension/blob/main/Frontend/popup.js) (Status and history UI), [`backend/url_feature_extractor.py`](https://github.com/bkg10/phishshield_extension/blob/main/backend/url_feature_extractor.py) (Feature extraction)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_extension["Browser extension"]
  node_navigation["Navigation monitor<br/>[background.js]"]
  node_scan["Scan orchestration<br/>[background.js]"]
  node_indicators["Page indicators<br/>[background.js]"]
  node_history[("Local scan history<br/>[background.js]")]
  node_popup["Status and history UI<br/>[popup.js]"]
end

subgraph group_backend["Detection backend"]
  node_api["Prediction API<br/>[app.py]"]
  node_extractor["Feature extraction"]
end

subgraph group_models["Inference assets"]
  node_scaler["Feature scaler<br/>[scaler.pkl]"]
  node_model["XGBoost classifier<br/>[xgb_model.json]"]
end

node_user(("Browser user"))
node_page(("Visited website"))
node_mlservice["Hosted inference service"]

node_user -->|"visits"| node_page
node_page -->|"navigation event"| node_navigation
node_navigation -->|"dispatches scan"| node_scan
node_scan -->|"posts URL"| node_mlservice
node_mlservice -.->|"routes prediction"| node_api
node_api -->|"extracts features"| node_extractor
node_api -->|"scales features"| node_scaler
node_api -->|"predicts verdict"| node_model
node_scan -->|"stores result"| node_history
node_scan -->|"shows verdict"| node_indicators
node_user -.->|"opens popup"| node_popup
node_popup -->|"requests status"| node_scan
node_popup -->|"requests history"| node_history

click node_navigation "https://github.com/bkg10/phishshield_extension/blob/main/Frontend/background.js"
click node_scan "https://github.com/bkg10/phishshield_extension/blob/main/Frontend/background.js"
click node_indicators "https://github.com/bkg10/phishshield_extension/blob/main/Frontend/background.js"
click node_history "https://github.com/bkg10/phishshield_extension/blob/main/Frontend/background.js"
click node_popup "https://github.com/bkg10/phishshield_extension/blob/main/Frontend/popup.js"
click node_api "https://github.com/bkg10/phishshield_extension/blob/main/backend/app.py"
click node_extractor "https://github.com/bkg10/phishshield_extension/blob/main/backend/url_feature_extractor.py"
click node_scaler "https://github.com/bkg10/phishshield_extension/blob/main/backend/scaler.pkl"
click node_model "https://github.com/bkg10/phishshield_extension/blob/main/backend/xgb_model.json"

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_scan,node_indicators,node_history,node_popup,node_user toneBlue
class node_api,node_extractor toneAmber
class node_scaler,node_model toneMint
class node_page,node_mlservice toneIndigo
```

## Components

### Browser extension

- [Navigation monitor](https://github.com/bkg10/phishshield_extension/blob/main/Frontend/background.js): `Frontend/background.js`
- [Scan orchestration](https://github.com/bkg10/phishshield_extension/blob/main/Frontend/background.js): `Frontend/background.js`
- [Page indicators](https://github.com/bkg10/phishshield_extension/blob/main/Frontend/background.js): `Frontend/background.js`
- [Local scan history](https://github.com/bkg10/phishshield_extension/blob/main/Frontend/background.js): `Frontend/background.js`
- [Status and history UI](https://github.com/bkg10/phishshield_extension/blob/main/Frontend/popup.js): `Frontend/popup.js`

### Detection backend

- [Prediction API](https://github.com/bkg10/phishshield_extension/blob/main/backend/app.py): `backend/app.py`
- [Feature extraction](https://github.com/bkg10/phishshield_extension/blob/main/backend/url_feature_extractor.py): `backend/url_feature_extractor.py`

### Inference assets

- [Feature scaler](https://github.com/bkg10/phishshield_extension/blob/main/backend/scaler.pkl): `backend/scaler.pkl`
- [XGBoost classifier](https://github.com/bkg10/phishshield_extension/blob/main/backend/xgb_model.json): `backend/xgb_model.json`

### Other components

- **Browser user**
- **Visited website**
- **Hosted inference service**

## Connections

- Browser user → Visited website: visits (evidence: `README.md`)
- Visited website → Navigation monitor: navigation event (evidence: `Frontend/background.js`)
- Navigation monitor → Scan orchestration: dispatches scan (evidence: `Frontend/background.js`)
- Scan orchestration → Hosted inference service: posts URL (evidence: `Frontend/background.js`)
- Hosted inference service → Prediction API: routes prediction (evidence: `README.md`)
- Prediction API → Feature extraction: extracts features (evidence: `backend/app.py`)
- Prediction API → Feature scaler: scales features (evidence: `backend/app.py`)
- Prediction API → XGBoost classifier: predicts verdict (evidence: `backend/app.py`)
- Scan orchestration → Local scan history: stores result (evidence: `Frontend/background.js`)
- Scan orchestration → Page indicators: shows verdict (evidence: `Frontend/background.js`)
- Browser user → Status and history UI: opens popup
- Status and history UI → Scan orchestration: requests status (evidence: `Frontend/popup.js`)
- Status and history UI → Local scan history: requests history (evidence: `Frontend/popup.js`)
