# khan123-code/gmail-phishing-detector architecture

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

- Interactive diagram: https://gitdiagram.com/khan123-code/gmail-phishing-detector
- Repository: https://github.com/khan123-code/gmail-phishing-detector

## Overview

Gmail Phishing Detector is a Chrome extension backed by a local Python API. Opening an email in Gmail triggers the content script to send its subject, sender, and body to the API; the scoring orchestrator gathers domain, credential, URL, semantic, and email-authentication signals, then returns a risk classification and explanation for the extension banner and popup. The README also describes offline ML training. The sampled runtime scorer shows weighted layer scoring, but does not show use of the trained model; some extension and training relationships are therefore omitted.

Main entry points: [`smart_predict.py`](https://github.com/khan123-code/gmail-phishing-detector/blob/main/smart_predict.py) (Risk Scorer), [`content.js`](https://github.com/khan123-code/gmail-phishing-detector/blob/main/content.js) (Email Scanner), [`app.py`](https://github.com/khan123-code/gmail-phishing-detector/blob/main/app.py) (Prediction API), [`email_auth_checker.py`](https://github.com/khan123-code/gmail-phishing-detector/blob/main/email_auth_checker.py) (Email Authentication)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_extension["Chrome Extension"]
  node_content["Email Scanner<br/>[content.js]"]
  node_banner["Risk Banner<br/>[content.js]"]
  node_result_storage[("Saved Result<br/>[content.js]")]
  node_popup["Popup Status<br/>[popup.js]"]
end

subgraph group_service["API Service"]
  node_api["Prediction API<br/>[app.py]"]
end

subgraph group_detection["Detection Layers"]
  node_scorer["Risk Scorer<br/>[smart_predict.py]"]
  node_domain["Domain Verification<br/>[domain_checker.py]"]
  node_credentials["Credential Detection"]
  node_urls["URL Analysis<br/>[url_analyzer.py]"]
  node_semantic["Semantic Analysis"]
  node_auth["Email Authentication"]
end

subgraph group_training["ML Training"]
  node_training["Model Training<br/>[train.py]"]
end

node_gmail(("Gmail Email"))
node_dns["DNS Resolver"]
node_dataset["Phishing Dataset"]

node_gmail -->|"opens email"| node_content
node_content -->|"sends email data"| node_api
node_api -->|"invokes scoring"| node_scorer
node_scorer -->|"checks sender"| node_domain
node_scorer -->|"detects requests"| node_credentials
node_scorer -->|"analyzes links"| node_urls
node_scorer -->|"classifies intent"| node_semantic
node_scorer -->|"checks authentication"| node_auth
node_auth -->|"queries records"| node_dns
node_scorer -->|"returns assessment"| node_api
node_api -->|"returns result"| node_content
node_content -->|"renders assessment"| node_banner
node_content -->|"saves result"| node_result_storage
node_popup -->|"reads result"| node_result_storage
node_dataset -->|"loads data"| node_training

click node_content "https://github.com/khan123-code/gmail-phishing-detector/blob/main/content.js"
click node_banner "https://github.com/khan123-code/gmail-phishing-detector/blob/main/content.js"
click node_result_storage "https://github.com/khan123-code/gmail-phishing-detector/blob/main/content.js"
click node_popup "https://github.com/khan123-code/gmail-phishing-detector/blob/main/popup.js"
click node_api "https://github.com/khan123-code/gmail-phishing-detector/blob/main/app.py"
click node_scorer "https://github.com/khan123-code/gmail-phishing-detector/blob/main/smart_predict.py"
click node_domain "https://github.com/khan123-code/gmail-phishing-detector/blob/main/domain_checker.py"
click node_credentials "https://github.com/khan123-code/gmail-phishing-detector/blob/main/credential_detector.py"
click node_urls "https://github.com/khan123-code/gmail-phishing-detector/blob/main/url_analyzer.py"
click node_semantic "https://github.com/khan123-code/gmail-phishing-detector/blob/main/semantic_analyzer.py"
click node_auth "https://github.com/khan123-code/gmail-phishing-detector/blob/main/email_auth_checker.py"
click node_training "https://github.com/khan123-code/gmail-phishing-detector/blob/main/train.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_content,node_banner,node_result_storage,node_popup toneBlue
class node_api toneAmber
class node_scorer,node_domain,node_credentials,node_urls,node_semantic,node_auth toneMint
class node_training toneRose
class node_gmail,node_dns,node_dataset toneIndigo
```

## Components

### Chrome Extension

- [Email Scanner](https://github.com/khan123-code/gmail-phishing-detector/blob/main/content.js): `content.js`
- [Risk Banner](https://github.com/khan123-code/gmail-phishing-detector/blob/main/content.js): `content.js`
- [Saved Result](https://github.com/khan123-code/gmail-phishing-detector/blob/main/content.js): `content.js`
- [Popup Status](https://github.com/khan123-code/gmail-phishing-detector/blob/main/popup.js): `popup.js`

### API Service

- [Prediction API](https://github.com/khan123-code/gmail-phishing-detector/blob/main/app.py): `app.py`

### Detection Layers

- [Risk Scorer](https://github.com/khan123-code/gmail-phishing-detector/blob/main/smart_predict.py): `smart_predict.py`
- [Domain Verification](https://github.com/khan123-code/gmail-phishing-detector/blob/main/domain_checker.py): `domain_checker.py`
- [Credential Detection](https://github.com/khan123-code/gmail-phishing-detector/blob/main/credential_detector.py): `credential_detector.py`
- [URL Analysis](https://github.com/khan123-code/gmail-phishing-detector/blob/main/url_analyzer.py): `url_analyzer.py`
- [Semantic Analysis](https://github.com/khan123-code/gmail-phishing-detector/blob/main/semantic_analyzer.py): `semantic_analyzer.py`
- [Email Authentication](https://github.com/khan123-code/gmail-phishing-detector/blob/main/email_auth_checker.py): `email_auth_checker.py`

### ML Training

- [Model Training](https://github.com/khan123-code/gmail-phishing-detector/blob/main/train.py): `train.py`

### Other components

- **Gmail Email**
- **DNS Resolver**
- **Phishing Dataset**

## Connections

- Gmail Email → Email Scanner: opens email (evidence: `content.js`)
- Email Scanner → Prediction API: sends email data (evidence: `content.js`)
- Prediction API → Risk Scorer: invokes scoring (evidence: `app.py`)
- Risk Scorer → Domain Verification: checks sender (evidence: `smart_predict.py`)
- Risk Scorer → Credential Detection: detects requests (evidence: `smart_predict.py`)
- Risk Scorer → URL Analysis: analyzes links (evidence: `smart_predict.py`)
- Risk Scorer → Semantic Analysis: classifies intent (evidence: `smart_predict.py`)
- Risk Scorer → Email Authentication: checks authentication (evidence: `smart_predict.py`)
- Email Authentication → DNS Resolver: queries records (evidence: `email_auth_checker.py`)
- Risk Scorer → Prediction API: returns assessment (evidence: `app.py`)
- Prediction API → Email Scanner: returns result (evidence: `content.js`)
- Email Scanner → Risk Banner: renders assessment (evidence: `content.js`)
- Email Scanner → Saved Result: saves result (evidence: `content.js`)
- Popup Status → Saved Result: reads result (evidence: `popup.js`)
- Phishing Dataset → Model Training: loads data (evidence: `train.py`)
