# kalkitarun1120/phishcatcher architecture

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

- Interactive diagram: https://gitdiagram.com/kalkitarun1120/phishcatcher
- Repository: https://github.com/kalkitarun1120/phishcatcher

## Overview

PhishCatcher is a Chrome extension backed by a Flask phishing-classification API. Its main workflow inspects a loaded page, derives URL and page-form features, requests a model prediction, then warns the user and may block form submissions; the popup also supports manual checks and displays recent results and statistics. A separate training workflow builds a logistic-regression model from the dataset and saves the artifact loaded by the API. The supplied source excerpts omit parts of the content script and training pipeline, so uncertain internal wiring is not shown.

Main entry points: [`extension/content.js`](https://github.com/kalkitarun1120/phishcatcher/blob/main/extension/content.js) (Page Analyzer), [`extension/popup.js`](https://github.com/kalkitarun1120/phishcatcher/blob/main/extension/popup.js) (Popup UI), [`backend/app.py`](https://github.com/kalkitarun1120/phishcatcher/blob/main/backend/app.py) (Prediction API), [`extension/background.js`](https://github.com/kalkitarun1120/phishcatcher/blob/main/extension/background.js) (Background Worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_extension["Chrome Extension"]
  node_popup["Popup UI<br/>[popup.js]"]
  node_content["Page Analyzer<br/>[content.js]"]
  node_warning["Warning and Form Guard<br/>[content.js]"]
  node_background["Background Worker<br/>[background.js]"]
end

subgraph group_backend["Detection Backend"]
  node_api["Prediction API<br/>[app.py]"]
  node_model["Classifier<br/>[app.py]"]
  node_artifact["Model Artifact<br/>[phishing_model.pkl]"]
end

subgraph group_training["Model Training"]
  node_trainer["Model Trainer<br/>[train_model.py]"]
  node_dataset["Phishing Dataset"]
end

subgraph group_state["Extension State"]
  node_storage[("Extension Storage")]
end

node_user(("User"))
node_page(("Web Page"))
node_chrome["Chrome APIs"]

node_user -->|"opens or checks"| node_popup
node_popup -->|"queries active tab"| node_chrome
node_popup -->|"sends check request"| node_content
node_page -->|"provides page content"| node_content
node_content -->|"posts features"| node_api
node_api -->|"predicts probability"| node_model
node_artifact -->|"loads at startup"| node_api
node_api -->|"returns prediction"| node_content
node_content -->|"writes last result"| node_storage
node_popup -->|"reads results and stats"| node_storage
node_content -->|"shows warning and blocks forms"| node_warning
node_content -->|"sends detection message"| node_background
node_background -->|"updates settings and stats"| node_storage
node_background -->|"updates badge and tabs"| node_chrome
node_trainer -->|"reads samples"| node_dataset
node_trainer -->|"saves trained model"| node_artifact
node_popup -->|"checks health"| node_api

click node_popup "https://github.com/kalkitarun1120/phishcatcher/blob/main/extension/popup.js"
click node_content "https://github.com/kalkitarun1120/phishcatcher/blob/main/extension/content.js"
click node_warning "https://github.com/kalkitarun1120/phishcatcher/blob/main/extension/content.js"
click node_background "https://github.com/kalkitarun1120/phishcatcher/blob/main/extension/background.js"
click node_api "https://github.com/kalkitarun1120/phishcatcher/blob/main/backend/app.py"
click node_model "https://github.com/kalkitarun1120/phishcatcher/blob/main/backend/app.py"
click node_trainer "https://github.com/kalkitarun1120/phishcatcher/blob/main/backend/train_model.py"
click node_dataset "https://github.com/kalkitarun1120/phishcatcher/blob/main/backend/phishing_dataset.csv"
click node_artifact "https://github.com/kalkitarun1120/phishcatcher/blob/main/backend/phishing_model.pkl"

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_content,node_warning,node_background,node_user toneBlue
class node_api,node_model,node_artifact toneAmber
class node_trainer,node_dataset,node_chrome toneMint
class node_storage toneRose
class node_page toneIndigo
```

## Components

### Chrome Extension

- [Popup UI](https://github.com/kalkitarun1120/phishcatcher/blob/main/extension/popup.js): `extension/popup.js`
- [Page Analyzer](https://github.com/kalkitarun1120/phishcatcher/blob/main/extension/content.js): `extension/content.js`
- [Warning and Form Guard](https://github.com/kalkitarun1120/phishcatcher/blob/main/extension/content.js): `extension/content.js`
- [Background Worker](https://github.com/kalkitarun1120/phishcatcher/blob/main/extension/background.js): `extension/background.js`

### Detection Backend

- [Prediction API](https://github.com/kalkitarun1120/phishcatcher/blob/main/backend/app.py): `backend/app.py`
- [Classifier](https://github.com/kalkitarun1120/phishcatcher/blob/main/backend/app.py): `backend/app.py`
- [Model Artifact](https://github.com/kalkitarun1120/phishcatcher/blob/main/backend/phishing_model.pkl): `backend/phishing_model.pkl`

### Model Training

- [Model Trainer](https://github.com/kalkitarun1120/phishcatcher/blob/main/backend/train_model.py): `backend/train_model.py`
- [Phishing Dataset](https://github.com/kalkitarun1120/phishcatcher/blob/main/backend/phishing_dataset.csv): `backend/phishing_dataset.csv`

### Extension State

- **Extension Storage**

### Other components

- **User**
- **Web Page**
- **Chrome APIs**

## Connections

- User → Popup UI: opens or checks
- Popup UI → Chrome APIs: queries active tab
- Popup UI → Page Analyzer: sends check request
- Web Page → Page Analyzer: provides page content
- Page Analyzer → Prediction API: posts features
- Prediction API → Classifier: predicts probability
- Model Artifact → Prediction API: loads at startup
- Prediction API → Page Analyzer: returns prediction
- Page Analyzer → Extension Storage: writes last result
- Popup UI → Extension Storage: reads results and stats
- Page Analyzer → Warning and Form Guard: shows warning and blocks forms
- Page Analyzer → Background Worker: sends detection message
- Background Worker → Extension Storage: updates settings and stats
- Background Worker → Chrome APIs: updates badge and tabs
- Model Trainer → Phishing Dataset: reads samples
- Model Trainer → Model Artifact: saves trained model
- Popup UI → Prediction API: checks health