# lyhenglong/phishing-detector architecture

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

- Interactive diagram: https://gitdiagram.com/lyhenglong/phishing-detector
- Repository: https://github.com/lyhenglong/phishing-detector

## Overview

Phishing URL Detector extracts structural signals from URLs and classifies them with a trained model. The main user workflow is entering one or more URLs through the Streamlit interface or REST API; the predictor extracts features, scales them, and returns a label, probability, and risk level. A separate training workflow builds features from labeled CSV data, trains and selects a classifier, and saves model artifacts. The README documents evaluation and feature-exploration capabilities; source excerpts show the standalone evaluator loading saved artifacts. Edges are limited to relationships shown in excerpts, the source index, or README; unsampled implementation details are not inferred.

Main entry points: [`src/predict.py`](https://github.com/lyhenglong/phishing-detector/blob/main/src/predict.py) (Prediction service), [`src/train_model.py`](https://github.com/lyhenglong/phishing-detector/blob/main/src/train_model.py) (Model training pipeline), [`src/evaluate.py`](https://github.com/lyhenglong/phishing-detector/blob/main/src/evaluate.py) (Standalone evaluator), [`utils/build_features.py`](https://github.com/lyhenglong/phishing-detector/blob/main/utils/build_features.py) (Feature dataset builder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_streamlit["Streamlit app<br/>[streamlit_app.py]"]
  node_api["REST API<br/>[api.py]"]
end

subgraph group_inference["Prediction runtime"]
  node_predictor["Prediction service<br/>[predict.py]"]
  node_extractor["URL feature extractor"]
  node_model["Trained classifier<br/>[best_model.pkl]"]
  node_scaler["Feature scaler<br/>[scaler.pkl]"]
  node_metadata["Model metadata<br/>[metadata.json]"]
end

subgraph group_training["Training and data"]
  node_rawdata["Labeled URL dataset"]
  node_featurebuilder["Feature dataset builder<br/>[build_features.py]"]
  node_featuredata["Extracted feature dataset"]
  node_trainer["Model training pipeline<br/>[train_model.py]"]
  node_synthetic["Synthetic data generator"]
end

subgraph group_evaluation["Evaluation"]
  node_evaluator["Standalone evaluator<br/>[evaluate.py]"]
end

node_user(("URL analyst"))

node_user -->|"submits URLs"| node_streamlit
node_user -->|"submits URLs"| node_api
node_streamlit -->|"requests predictions"| node_predictor
node_api -->|"requests predictions"| node_predictor
node_predictor -->|"extracts features"| node_extractor
node_predictor -->|"loads and applies"| node_scaler
node_predictor -->|"loads and predicts"| node_model
node_predictor -->|"loads metadata"| node_metadata
node_rawdata -->|"provides labeled URLs"| node_featurebuilder
node_featurebuilder -->|"extracts features"| node_extractor
node_featurebuilder -->|"writes features"| node_featuredata
node_trainer -->|"builds if missing"| node_featurebuilder
node_trainer -->|"loads features"| node_featuredata
node_trainer -->|"saves selected model"| node_model
node_trainer -->|"saves scaler"| node_scaler
node_trainer -->|"saves metadata"| node_metadata
node_evaluator -->|"loads model"| node_model
node_evaluator -->|"loads scaler"| node_scaler
node_evaluator -->|"loads and updates"| node_metadata
node_evaluator -.->|"reads evaluation data"| node_featuredata

click node_streamlit "https://github.com/lyhenglong/phishing-detector/blob/main/app/streamlit_app.py"
click node_api "https://github.com/lyhenglong/phishing-detector/blob/main/app/api.py"
click node_predictor "https://github.com/lyhenglong/phishing-detector/blob/main/src/predict.py"
click node_extractor "https://github.com/lyhenglong/phishing-detector/blob/main/src/feature_extraction.py"
click node_model "https://github.com/lyhenglong/phishing-detector/blob/main/models/best_model.pkl"
click node_scaler "https://github.com/lyhenglong/phishing-detector/blob/main/models/scaler.pkl"
click node_metadata "https://github.com/lyhenglong/phishing-detector/blob/main/models/metadata.json"
click node_rawdata "https://github.com/lyhenglong/phishing-detector/blob/main/data/phishing_dataset_v1.csv"
click node_featurebuilder "https://github.com/lyhenglong/phishing-detector/blob/main/utils/build_features.py"
click node_featuredata "https://github.com/lyhenglong/phishing-detector/blob/main/data/phishing_dataset_v1_features.csv"
click node_trainer "https://github.com/lyhenglong/phishing-detector/blob/main/src/train_model.py"
click node_synthetic "https://github.com/lyhenglong/phishing-detector/blob/main/utils/generate_dataset.py"
click node_evaluator "https://github.com/lyhenglong/phishing-detector/blob/main/src/evaluate.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_streamlit,node_api toneBlue
class node_predictor,node_extractor,node_model,node_scaler,node_metadata toneAmber
class node_rawdata,node_featurebuilder,node_featuredata,node_trainer,node_synthetic toneMint
class node_evaluator toneRose
class node_user toneIndigo
```

## Components

### User interfaces

- [Streamlit app](https://github.com/lyhenglong/phishing-detector/blob/main/app/streamlit_app.py): `app/streamlit_app.py`
- [REST API](https://github.com/lyhenglong/phishing-detector/blob/main/app/api.py): `app/api.py`

### Prediction runtime

- [Prediction service](https://github.com/lyhenglong/phishing-detector/blob/main/src/predict.py): `src/predict.py`
- [URL feature extractor](https://github.com/lyhenglong/phishing-detector/blob/main/src/feature_extraction.py): `src/feature_extraction.py`
- [Trained classifier](https://github.com/lyhenglong/phishing-detector/blob/main/models/best_model.pkl): `models/best_model.pkl`
- [Feature scaler](https://github.com/lyhenglong/phishing-detector/blob/main/models/scaler.pkl): `models/scaler.pkl`
- [Model metadata](https://github.com/lyhenglong/phishing-detector/blob/main/models/metadata.json): `models/metadata.json`

### Training and data

- [Labeled URL dataset](https://github.com/lyhenglong/phishing-detector/blob/main/data/phishing_dataset_v1.csv): `data/phishing_dataset_v1.csv`
- [Feature dataset builder](https://github.com/lyhenglong/phishing-detector/blob/main/utils/build_features.py): `utils/build_features.py`
- [Extracted feature dataset](https://github.com/lyhenglong/phishing-detector/blob/main/data/phishing_dataset_v1_features.csv): `data/phishing_dataset_v1_features.csv`
- [Model training pipeline](https://github.com/lyhenglong/phishing-detector/blob/main/src/train_model.py): `src/train_model.py`
- [Synthetic data generator](https://github.com/lyhenglong/phishing-detector/blob/main/utils/generate_dataset.py): `utils/generate_dataset.py`

### Evaluation

- [Standalone evaluator](https://github.com/lyhenglong/phishing-detector/blob/main/src/evaluate.py): `src/evaluate.py`

### Other components

- **URL analyst**

## Connections

- URL analyst → Streamlit app: submits URLs (evidence: `README.md`)
- URL analyst → REST API: submits URLs (evidence: `README.md`)
- Streamlit app → Prediction service: requests predictions (evidence: `app/streamlit_app.py`)
- REST API → Prediction service: requests predictions (evidence: `app/api.py`)
- Prediction service → URL feature extractor: extracts features (evidence: `src/predict.py`)
- Prediction service → Feature scaler: loads and applies (evidence: `src/predict.py`)
- Prediction service → Trained classifier: loads and predicts (evidence: `src/predict.py`)
- Prediction service → Model metadata: loads metadata (evidence: `src/predict.py`)
- Labeled URL dataset → Feature dataset builder: provides labeled URLs (evidence: `README.md`)
- Feature dataset builder → URL feature extractor: extracts features (evidence: `utils/build_features.py`)
- Feature dataset builder → Extracted feature dataset: writes features (evidence: `utils/build_features.py`)
- Model training pipeline → Feature dataset builder: builds if missing (evidence: `src/train_model.py`)
- Model training pipeline → Extracted feature dataset: loads features (evidence: `README.md`)
- Model training pipeline → Trained classifier: saves selected model (evidence: `README.md`)
- Model training pipeline → Feature scaler: saves scaler (evidence: `README.md`)
- Model training pipeline → Model metadata: saves metadata (evidence: `README.md`)
- Standalone evaluator → Trained classifier: loads model (evidence: `src/evaluate.py`)
- Standalone evaluator → Feature scaler: loads scaler (evidence: `src/evaluate.py`)
- Standalone evaluator → Model metadata: loads and updates (evidence: `src/evaluate.py`)
- Standalone evaluator → Extracted feature dataset: reads evaluation data
