# wasim-khans/msc-project-ml-webdev-phishingdetection architecture

> Architecture diagram of the GitHub repository wasim-khans/msc-project-ml-webdev-phishingdetection, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wasim-khans/msc-project-ml-webdev-phishingdetection
- Repository: https://github.com/wasim-khans/msc-project-ml-webdev-phishingdetection

## Overview

Phishing URL Detection is a research project with a web prediction app and a reproducible model-comparison workflow. In the app, a user submits a URL and selects a model; the frontend calls the API, which extracts URL features, loads the selected model and returns a prediction for display and recent-session history. Separately, the ML workflow prepares main and external datasets, trains models, evaluates cross-dataset performance and produces a combined report. The graph includes documented stages whose implementation was not sampled; those links rely on the README rather than inspected script bodies.

Main entry points: [`frontend/src/pages/HomePage.jsx`](https://github.com/wasim-khans/msc-project-ml-webdev-phishingdetection/blob/main/frontend/src/pages/HomePage.jsx) (Home page), [`backend/app/controllers/prediction_controller.py`](https://github.com/wasim-khans/msc-project-ml-webdev-phishingdetection/blob/main/backend/app/controllers/prediction_controller.py) (Prediction routes), [`backend/app/core/dependencies.py`](https://github.com/wasim-khans/msc-project-ml-webdev-phishingdetection/blob/main/backend/app/core/dependencies.py) (Service wiring), [`backend/app/services/prediction_service.py`](https://github.com/wasim-khans/msc-project-ml-webdev-phishingdetection/blob/main/backend/app/services/prediction_service.py) (Prediction service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web interface"]
  node_home["Home page<br/>[HomePage.jsx]"]
  node_urlpanel["URL input"]
  node_predictionpanel["Prediction display"]
  node_history["Recent results"]
  node_modelinsights["Model insights"]
  node_modelhook["Model state<br/>[useModelInfo.js]"]
  node_predictionhook["Prediction state"]
  node_historyhook["History state"]
  node_predictionapi["Prediction API client<br/>[predictionApi.js]"]
  node_apiclient["HTTP client<br/>[apiClient.js]"]
  node_formatters["Result formatters<br/>[formatters.js]"]
  node_featuremeta["Feature metadata<br/>[featureMetadata.js]"]
end

subgraph group_api["Prediction API"]
  node_server["FastAPI app<br/>[main.py]"]
  node_routes["Prediction routes"]
  node_settings["API settings<br/>[settings.py]"]
  node_dependencies["Service wiring<br/>[dependencies.py]"]
  node_schemas["API schemas<br/>[prediction.py]"]
end

subgraph group_inference["Inference"]
  node_service["Prediction service"]
  node_repository["Model repository"]
  node_extractor["URL feature extraction"]
end

subgraph group_experiments["ML experiments"]
  node_mainprep["Main dataset preparation"]
  node_externalprep["External dataset preparation"]
  node_splits["Dataset splits"]
  node_maintraining["Main model training"]
  node_externaltesting["External model testing"]
  node_crossconfig["Cross-dataset config"]
  node_crosstraining["Cross-dataset training"]
  node_crosseval["Cross-dataset evaluation"]
end

subgraph group_reporting["Research reporting"]
  node_report["Combined experiment report"]
  node_paths["Project paths<br/>[project_paths.py]"]
end

node_user(("User"))

node_user -->|"uses"| node_home
node_home -->|"renders"| node_urlpanel
node_home -->|"renders"| node_predictionpanel
node_home -->|"renders"| node_history
node_home -->|"loads model state"| node_modelhook
node_home -->|"submits URL"| node_predictionhook
node_home -->|"records prediction"| node_historyhook
node_modelhook -->|"requests model info"| node_predictionapi
node_predictionhook -->|"requests prediction"| node_predictionapi
node_home -.-> node_modelinsights
node_predictionapi -->|"uses HTTP client"| node_apiclient
node_user -.->|"receives prediction"| node_server
node_server -->|"mounts routes"| node_routes
node_server -->|"loads settings"| node_settings
node_routes -->|"resolves service"| node_dependencies
node_routes -->|"validates responses"| node_schemas
node_routes -->|"calls service"| node_service
node_dependencies -->|"reads configuration"| node_settings
node_dependencies -->|"constructs repository"| node_repository
node_dependencies -->|"constructs service"| node_service
node_service -->|"loads model assets"| node_repository
node_service -->|"extracts features"| node_extractor
node_home -.-> node_formatters
node_formatters -->|"reads feature metadata"| node_featuremeta
node_mainprep -.->|"extracts URL features"| node_extractor
node_mainprep -->|"prepares main data"| node_splits
node_externalprep -->|"prepares external data"| node_splits
node_splits -->|"feeds training"| node_maintraining
node_maintraining -->|"tests trained models"| node_externaltesting
node_splits -->|"feeds cross-dataset training"| node_crosstraining
node_crossconfig -->|"uses project paths"| node_paths
node_crosseval -->|"uses configuration"| node_crossconfig
node_crosseval -->|"uses training helpers"| node_crosstraining
node_crosstraining -->|"uses configuration"| node_crossconfig
node_crosseval -.->|"produces experiment results"| node_report
node_report -->|"uses project paths"| node_paths

click node_home "https://github.com/wasim-khans/msc-project-ml-webdev-phishingdetection/blob/main/frontend/src/pages/HomePage.jsx"
click node_urlpanel "https://github.com/wasim-khans/msc-project-ml-webdev-phishingdetection/blob/main/frontend/src/components/UrlAnalysisPanel.jsx"
click node_predictionpanel "https://github.com/wasim-khans/msc-project-ml-webdev-phishingdetection/blob/main/frontend/src/components/PredictionPanel.jsx"
click node_history "https://github.com/wasim-khans/msc-project-ml-webdev-phishingdetection/blob/main/frontend/src/components/ResultsHistorySection.jsx"
click node_modelinsights "https://github.com/wasim-khans/msc-project-ml-webdev-phishingdetection/blob/main/frontend/src/components/ModelInsightsPanel.jsx"
click node_modelhook "https://github.com/wasim-khans/msc-project-ml-webdev-phishingdetection/blob/main/frontend/src/hooks/useModelInfo.js"
click node_predictionhook "https://github.com/wasim-khans/msc-project-ml-webdev-phishingdetection/blob/main/frontend/src/hooks/useUrlPrediction.js"
click node_historyhook "https://github.com/wasim-khans/msc-project-ml-webdev-phishingdetection/blob/main/frontend/src/hooks/usePredictionHistory.js"
click node_predictionapi "https://github.com/wasim-khans/msc-project-ml-webdev-phishingdetection/blob/main/frontend/src/services/predictionApi.js"
click node_apiclient "https://github.com/wasim-khans/msc-project-ml-webdev-phishingdetection/blob/main/frontend/src/services/apiClient.js"
click node_formatters "https://github.com/wasim-khans/msc-project-ml-webdev-phishingdetection/blob/main/frontend/src/lib/formatters.js"
click node_featuremeta "https://github.com/wasim-khans/msc-project-ml-webdev-phishingdetection/blob/main/frontend/src/lib/featureMetadata.js"
click node_server "https://github.com/wasim-khans/msc-project-ml-webdev-phishingdetection/blob/main/backend/app/main.py"
click node_routes "https://github.com/wasim-khans/msc-project-ml-webdev-phishingdetection/blob/main/backend/app/controllers/prediction_controller.py"
click node_settings "https://github.com/wasim-khans/msc-project-ml-webdev-phishingdetection/blob/main/backend/app/core/settings.py"
click node_dependencies "https://github.com/wasim-khans/msc-project-ml-webdev-phishingdetection/blob/main/backend/app/core/dependencies.py"
click node_schemas "https://github.com/wasim-khans/msc-project-ml-webdev-phishingdetection/blob/main/backend/app/schemas/prediction.py"
click node_service "https://github.com/wasim-khans/msc-project-ml-webdev-phishingdetection/blob/main/backend/app/services/prediction_service.py"
click node_repository "https://github.com/wasim-khans/msc-project-ml-webdev-phishingdetection/blob/main/backend/app/repositories/model_repository.py"
click node_extractor "https://github.com/wasim-khans/msc-project-ml-webdev-phishingdetection/blob/main/machine_learning/scripts/core/url_feature_extractor.py"
click node_mainprep "https://github.com/wasim-khans/msc-project-ml-webdev-phishingdetection/blob/main/machine_learning/scripts/1a_2_build_main_feature_dataset.py"
click node_externalprep "https://github.com/wasim-khans/msc-project-ml-webdev-phishingdetection/blob/main/machine_learning/scripts/1b_1_prepare_external_testing_datasets.py"
click node_splits "https://github.com/wasim-khans/msc-project-ml-webdev-phishingdetection/blob/main/machine_learning/scripts/2_1_build_cross_dataset_splits.py"
click node_maintraining "https://github.com/wasim-khans/msc-project-ml-webdev-phishingdetection/blob/main/machine_learning/scripts/1a_4_train_main_models.py"
click node_externaltesting "https://github.com/wasim-khans/msc-project-ml-webdev-phishingdetection/blob/main/machine_learning/scripts/1b_2_test_main_models_on_external_datasets.py"
click node_crossconfig "https://github.com/wasim-khans/msc-project-ml-webdev-phishingdetection/blob/main/machine_learning/scripts/helpers/cross_dataset_config.py"
click node_crosstraining "https://github.com/wasim-khans/msc-project-ml-webdev-phishingdetection/blob/main/machine_learning/scripts/helpers/cross_dataset_model_training.py"
click node_crosseval "https://github.com/wasim-khans/msc-project-ml-webdev-phishingdetection/blob/main/machine_learning/scripts/helpers/cross_dataset_evaluation.py"
click node_report "https://github.com/wasim-khans/msc-project-ml-webdev-phishingdetection/blob/main/machine_learning/scripts/build_all_experiments_combined_report.py"
click node_paths "https://github.com/wasim-khans/msc-project-ml-webdev-phishingdetection/blob/main/machine_learning/scripts/helpers/project_paths.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_home,node_urlpanel,node_predictionpanel,node_history,node_modelinsights,node_modelhook,node_predictionhook,node_historyhook,node_predictionapi,node_apiclient,node_formatters,node_featuremeta,node_user toneBlue
class node_server,node_routes,node_settings,node_dependencies,node_schemas toneAmber
class node_service,node_repository,node_extractor toneMint
class node_mainprep,node_externalprep,node_splits,node_maintraining,node_externaltesting,node_crossconfig,node_crosstraining,node_crosseval toneRose
class node_report,node_paths toneIndigo
```

## Components

### Web interface

- [Home page](https://github.com/wasim-khans/msc-project-ml-webdev-phishingdetection/blob/main/frontend/src/pages/HomePage.jsx): `frontend/src/pages/HomePage.jsx`
- [URL input](https://github.com/wasim-khans/msc-project-ml-webdev-phishingdetection/blob/main/frontend/src/components/UrlAnalysisPanel.jsx): `frontend/src/components/UrlAnalysisPanel.jsx`
- [Prediction display](https://github.com/wasim-khans/msc-project-ml-webdev-phishingdetection/blob/main/frontend/src/components/PredictionPanel.jsx): `frontend/src/components/PredictionPanel.jsx`
- [Recent results](https://github.com/wasim-khans/msc-project-ml-webdev-phishingdetection/blob/main/frontend/src/components/ResultsHistorySection.jsx): `frontend/src/components/ResultsHistorySection.jsx`
- [Model insights](https://github.com/wasim-khans/msc-project-ml-webdev-phishingdetection/blob/main/frontend/src/components/ModelInsightsPanel.jsx): `frontend/src/components/ModelInsightsPanel.jsx`
- [Model state](https://github.com/wasim-khans/msc-project-ml-webdev-phishingdetection/blob/main/frontend/src/hooks/useModelInfo.js): `frontend/src/hooks/useModelInfo.js`
- [Prediction state](https://github.com/wasim-khans/msc-project-ml-webdev-phishingdetection/blob/main/frontend/src/hooks/useUrlPrediction.js): `frontend/src/hooks/useUrlPrediction.js`
- [History state](https://github.com/wasim-khans/msc-project-ml-webdev-phishingdetection/blob/main/frontend/src/hooks/usePredictionHistory.js): `frontend/src/hooks/usePredictionHistory.js`
- [Prediction API client](https://github.com/wasim-khans/msc-project-ml-webdev-phishingdetection/blob/main/frontend/src/services/predictionApi.js): `frontend/src/services/predictionApi.js`
- [HTTP client](https://github.com/wasim-khans/msc-project-ml-webdev-phishingdetection/blob/main/frontend/src/services/apiClient.js): `frontend/src/services/apiClient.js`
- [Result formatters](https://github.com/wasim-khans/msc-project-ml-webdev-phishingdetection/blob/main/frontend/src/lib/formatters.js): `frontend/src/lib/formatters.js`
- [Feature metadata](https://github.com/wasim-khans/msc-project-ml-webdev-phishingdetection/blob/main/frontend/src/lib/featureMetadata.js): `frontend/src/lib/featureMetadata.js`

### Prediction API

- [FastAPI app](https://github.com/wasim-khans/msc-project-ml-webdev-phishingdetection/blob/main/backend/app/main.py): `backend/app/main.py`
- [Prediction routes](https://github.com/wasim-khans/msc-project-ml-webdev-phishingdetection/blob/main/backend/app/controllers/prediction_controller.py): `backend/app/controllers/prediction_controller.py`
- [API settings](https://github.com/wasim-khans/msc-project-ml-webdev-phishingdetection/blob/main/backend/app/core/settings.py): `backend/app/core/settings.py`
- [Service wiring](https://github.com/wasim-khans/msc-project-ml-webdev-phishingdetection/blob/main/backend/app/core/dependencies.py): `backend/app/core/dependencies.py`
- [API schemas](https://github.com/wasim-khans/msc-project-ml-webdev-phishingdetection/blob/main/backend/app/schemas/prediction.py): `backend/app/schemas/prediction.py`

### Inference

- [Prediction service](https://github.com/wasim-khans/msc-project-ml-webdev-phishingdetection/blob/main/backend/app/services/prediction_service.py): `backend/app/services/prediction_service.py`
- [Model repository](https://github.com/wasim-khans/msc-project-ml-webdev-phishingdetection/blob/main/backend/app/repositories/model_repository.py): `backend/app/repositories/model_repository.py`
- [URL feature extraction](https://github.com/wasim-khans/msc-project-ml-webdev-phishingdetection/blob/main/machine_learning/scripts/core/url_feature_extractor.py): `machine_learning/scripts/core/url_feature_extractor.py`

### ML experiments

- [Main dataset preparation](https://github.com/wasim-khans/msc-project-ml-webdev-phishingdetection/blob/main/machine_learning/scripts/1a_2_build_main_feature_dataset.py): `machine_learning/scripts/1a_2_build_main_feature_dataset.py`
- [External dataset preparation](https://github.com/wasim-khans/msc-project-ml-webdev-phishingdetection/blob/main/machine_learning/scripts/1b_1_prepare_external_testing_datasets.py): `machine_learning/scripts/1b_1_prepare_external_testing_datasets.py`
- [Dataset splits](https://github.com/wasim-khans/msc-project-ml-webdev-phishingdetection/blob/main/machine_learning/scripts/2_1_build_cross_dataset_splits.py): `machine_learning/scripts/2_1_build_cross_dataset_splits.py`
- [Main model training](https://github.com/wasim-khans/msc-project-ml-webdev-phishingdetection/blob/main/machine_learning/scripts/1a_4_train_main_models.py): `machine_learning/scripts/1a_4_train_main_models.py`
- [External model testing](https://github.com/wasim-khans/msc-project-ml-webdev-phishingdetection/blob/main/machine_learning/scripts/1b_2_test_main_models_on_external_datasets.py): `machine_learning/scripts/1b_2_test_main_models_on_external_datasets.py`
- [Cross-dataset config](https://github.com/wasim-khans/msc-project-ml-webdev-phishingdetection/blob/main/machine_learning/scripts/helpers/cross_dataset_config.py): `machine_learning/scripts/helpers/cross_dataset_config.py`
- [Cross-dataset training](https://github.com/wasim-khans/msc-project-ml-webdev-phishingdetection/blob/main/machine_learning/scripts/helpers/cross_dataset_model_training.py): `machine_learning/scripts/helpers/cross_dataset_model_training.py`
- [Cross-dataset evaluation](https://github.com/wasim-khans/msc-project-ml-webdev-phishingdetection/blob/main/machine_learning/scripts/helpers/cross_dataset_evaluation.py): `machine_learning/scripts/helpers/cross_dataset_evaluation.py`

### Research reporting

- [Combined experiment report](https://github.com/wasim-khans/msc-project-ml-webdev-phishingdetection/blob/main/machine_learning/scripts/build_all_experiments_combined_report.py): `machine_learning/scripts/build_all_experiments_combined_report.py`
- [Project paths](https://github.com/wasim-khans/msc-project-ml-webdev-phishingdetection/blob/main/machine_learning/scripts/helpers/project_paths.py): `machine_learning/scripts/helpers/project_paths.py`

### Other components

- **User**

## Connections

- User → Home page: uses (evidence: `README.md`)
- Home page → URL input: renders (evidence: `frontend/src/pages/HomePage.jsx`)
- Home page → Prediction display: renders (evidence: `frontend/src/pages/HomePage.jsx`)
- Home page → Recent results: renders (evidence: `frontend/src/pages/HomePage.jsx`)
- Home page → Model state: loads model state (evidence: `frontend/src/pages/HomePage.jsx`)
- Home page → Prediction state: submits URL (evidence: `frontend/src/pages/HomePage.jsx`)
- Home page → History state: records prediction (evidence: `frontend/src/pages/HomePage.jsx`)
- Model state → Prediction API client: requests model info (evidence: `frontend/src/hooks/useModelInfo.js`)
- Prediction state → Prediction API client: requests prediction (evidence: `frontend/src/hooks/useUrlPrediction.js`)
- Home page → Model insights
- Prediction API client → HTTP client: uses HTTP client (evidence: `frontend/src/services/predictionApi.js`)
- User → FastAPI app: receives prediction (evidence: `README.md`)
- FastAPI app → Prediction routes: mounts routes (evidence: `backend/app/main.py`)
- FastAPI app → API settings: loads settings (evidence: `backend/app/main.py`)
- Prediction routes → Service wiring: resolves service (evidence: `backend/app/controllers/prediction_controller.py`)
- Prediction routes → API schemas: validates responses (evidence: `backend/app/controllers/prediction_controller.py`)
- Prediction routes → Prediction service: calls service (evidence: `backend/app/controllers/prediction_controller.py`)
- Service wiring → API settings: reads configuration (evidence: `backend/app/core/dependencies.py`)
- Service wiring → Model repository: constructs repository (evidence: `backend/app/core/dependencies.py`)
- Service wiring → Prediction service: constructs service (evidence: `backend/app/core/dependencies.py`)
- Prediction service → Model repository: loads model assets (evidence: `backend/app/services/prediction_service.py`)
- Prediction service → URL feature extraction: extracts features (evidence: `backend/app/services/prediction_service.py`)
- Home page → Result formatters
- Result formatters → Feature metadata: reads feature metadata (evidence: `frontend/src/lib/formatters.js`)
- Main dataset preparation → URL feature extraction: extracts URL features (evidence: `README.md`)
- Main dataset preparation → Dataset splits: prepares main data (evidence: `README.md`)
- External dataset preparation → Dataset splits: prepares external data (evidence: `README.md`)
- Dataset splits → Main model training: feeds training (evidence: `README.md`)
- Main model training → External model testing: tests trained models (evidence: `README.md`)
- Dataset splits → Cross-dataset training: feeds cross-dataset training (evidence: `README.md`)
- Cross-dataset config → Project paths: uses project paths (evidence: `machine_learning/scripts/helpers/cross_dataset_config.py`)
- Cross-dataset evaluation → Cross-dataset config: uses configuration (evidence: `machine_learning/scripts/helpers/cross_dataset_evaluation.py`)
- Cross-dataset evaluation → Cross-dataset training: uses training helpers (evidence: `machine_learning/scripts/helpers/cross_dataset_evaluation.py`)
- Cross-dataset training → Cross-dataset config: uses configuration (evidence: `machine_learning/scripts/helpers/cross_dataset_model_training.py`)
- Cross-dataset evaluation → Combined experiment report: produces experiment results
- Combined experiment report → Project paths: uses project paths (evidence: `machine_learning/scripts/build_all_experiments_combined_report.py`)
