# tarequesyed/phishing-detector architecture

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

## Overview

AI Phishing Detector accepts email text in a browser dashboard and returns heuristic, URL, and LLM risk scores plus an explanation. The Flask analysis route coordinates URL extraction and the three analysis channels, combines their scores, attempts to persist a scan, and returns the results for display. Scan history is the documented audit capability. The README also documents PostgreSQL as the persistent store. Source excerpts show the scoring and persistence calls; other README-described deployment details are not runtime product components here.

Main entry points: [`backend/routes/analyze.py`](https://github.com/tarequesyed/phishing-detector/blob/main/backend/routes/analyze.py) (Analysis route), [`frontend/script.js`](https://github.com/tarequesyed/phishing-detector/blob/main/frontend/script.js) (Dashboard behavior), [`frontend/index.html`](https://github.com/tarequesyed/phishing-detector/blob/main/frontend/index.html) (Analysis dashboard), [`backend/analyser/llm_detector.py`](https://github.com/tarequesyed/phishing-detector/blob/main/backend/analyser/llm_detector.py) (LLM analysis)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Browser interface"]
  node_dashboard["Analysis dashboard<br/>[index.html]"]
  node_browser["Dashboard behavior<br/>[script.js]"]
end

subgraph group_api["Flask API"]
  node_app["Flask application<br/>[app.py]"]
  node_analyze["Analysis route<br/>[analyze.py]"]
end

subgraph group_analysis["Phishing analysis"]
  node_extract["URL extraction<br/>[url_detector.py]"]
  node_heuristic["Keyword scoring<br/>[heuristic.py]"]
  node_urlrisk["URL risk scoring<br/>[url_risk.py]"]
  node_llm["LLM analysis<br/>[llm_detector.py]"]
  node_scoring["Score combination<br/>[scoring.py]"]
end

subgraph group_persistence["Scan persistence"]
  node_scan["Scan record<br/>[scan.py]"]
  node_db["SQLAlchemy database<br/>[database.py]"]
end

node_user(("Email submitter"))
node_hf{{"Hugging Face API"}}
node_postgres[("PostgreSQL")]

node_user -->|"enters email"| node_dashboard
node_dashboard -->|"runs analysis"| node_browser
node_browser -->|"POST email"| node_analyze
node_app -->|"registers route"| node_analyze
node_analyze -->|"extracts URLs"| node_extract
node_analyze -->|"scores keywords"| node_heuristic
node_analyze -->|"scores URLs"| node_urlrisk
node_analyze -->|"requests analysis"| node_llm
node_llm -->|"queries model"| node_hf
node_analyze -->|"combines scores"| node_scoring
node_analyze -->|"creates record"| node_scan
node_analyze -->|"commits scan"| node_db
node_db -->|"persists data"| node_postgres
node_analyze -->|"returns results"| node_browser

click node_dashboard "https://github.com/tarequesyed/phishing-detector/blob/main/frontend/index.html"
click node_browser "https://github.com/tarequesyed/phishing-detector/blob/main/frontend/script.js"
click node_app "https://github.com/tarequesyed/phishing-detector/blob/main/backend/app.py"
click node_analyze "https://github.com/tarequesyed/phishing-detector/blob/main/backend/routes/analyze.py"
click node_extract "https://github.com/tarequesyed/phishing-detector/blob/main/backend/analyser/url_detector.py"
click node_heuristic "https://github.com/tarequesyed/phishing-detector/blob/main/backend/analyser/heuristic.py"
click node_urlrisk "https://github.com/tarequesyed/phishing-detector/blob/main/backend/analyser/url_risk.py"
click node_llm "https://github.com/tarequesyed/phishing-detector/blob/main/backend/analyser/llm_detector.py"
click node_scoring "https://github.com/tarequesyed/phishing-detector/blob/main/backend/analyser/scoring.py"
click node_scan "https://github.com/tarequesyed/phishing-detector/blob/main/backend/models/scan.py"
click node_db "https://github.com/tarequesyed/phishing-detector/blob/main/backend/database.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_dashboard,node_browser toneBlue
class node_app,node_analyze,node_postgres toneAmber
class node_extract,node_heuristic,node_urlrisk,node_llm,node_scoring,node_hf toneMint
class node_scan,node_db toneRose
class node_user toneIndigo
```

## Components

### Browser interface

- [Analysis dashboard](https://github.com/tarequesyed/phishing-detector/blob/main/frontend/index.html): `frontend/index.html`
- [Dashboard behavior](https://github.com/tarequesyed/phishing-detector/blob/main/frontend/script.js): `frontend/script.js`

### Flask API

- [Flask application](https://github.com/tarequesyed/phishing-detector/blob/main/backend/app.py): `backend/app.py`
- [Analysis route](https://github.com/tarequesyed/phishing-detector/blob/main/backend/routes/analyze.py): `backend/routes/analyze.py`

### Phishing analysis

- [URL extraction](https://github.com/tarequesyed/phishing-detector/blob/main/backend/analyser/url_detector.py): `backend/analyser/url_detector.py`
- [Keyword scoring](https://github.com/tarequesyed/phishing-detector/blob/main/backend/analyser/heuristic.py): `backend/analyser/heuristic.py`
- [URL risk scoring](https://github.com/tarequesyed/phishing-detector/blob/main/backend/analyser/url_risk.py): `backend/analyser/url_risk.py`
- [LLM analysis](https://github.com/tarequesyed/phishing-detector/blob/main/backend/analyser/llm_detector.py): `backend/analyser/llm_detector.py`
- [Score combination](https://github.com/tarequesyed/phishing-detector/blob/main/backend/analyser/scoring.py): `backend/analyser/scoring.py`

### Scan persistence

- [Scan record](https://github.com/tarequesyed/phishing-detector/blob/main/backend/models/scan.py): `backend/models/scan.py`
- [SQLAlchemy database](https://github.com/tarequesyed/phishing-detector/blob/main/backend/database.py): `backend/database.py`

### Other components

- **Email submitter**
- **Hugging Face API**
- **PostgreSQL**

## Connections

- Email submitter → Analysis dashboard: enters email
- Analysis dashboard → Dashboard behavior: runs analysis
- Dashboard behavior → Analysis route: POST email
- Flask application → Analysis route: registers route
- Analysis route → URL extraction: extracts URLs
- Analysis route → Keyword scoring: scores keywords
- Analysis route → URL risk scoring: scores URLs
- Analysis route → LLM analysis: requests analysis
- LLM analysis → Hugging Face API: queries model
- Analysis route → Score combination: combines scores
- Analysis route → Scan record: creates record
- Analysis route → SQLAlchemy database: commits scan
- SQLAlchemy database → PostgreSQL: persists data
- Analysis route → Dashboard behavior: returns results