# ducvovn01/phishing_url_project architecture

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

- Interactive diagram: https://gitdiagram.com/ducvovn01/phishing_url_project
- Repository: https://github.com/ducvovn01/phishing_url_project

## Overview

This is a browser-based phishing URL detector: a user submits URL text, the React client sends it to FastAPI, and the service returns a phishing verdict, trust score, and explanatory signals. The client presents the result and can compare checks in tab-local session summaries. The backend validates and scores text offline with a verified char n-gram model, without fetching URLs or making reputation lookups. The README also documents an offline model-training pipeline. Backend internals and some UI wiring are supported by the excerpts and SOURCE INDEX; unsampled implementation details are not inferred.

Main entry points: [`backend/app/services/model_service.py`](https://github.com/ducvovn01/phishing_url_project/blob/main/backend/app/services/model_service.py) (Model service), [`backend/app/main.py`](https://github.com/ducvovn01/phishing_url_project/blob/main/backend/app/main.py) (FastAPI app), [`frontend/src/pages/HomePage.jsx`](https://github.com/ducvovn01/phishing_url_project/blob/main/frontend/src/pages/HomePage.jsx) (URL checker), [`frontend/src/api/client.js`](https://github.com/ducvovn01/phishing_url_project/blob/main/frontend/src/api/client.js) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_app["App routes<br/>[App.jsx]"]
  node_home["URL checker<br/>[HomePage.jsx]"]
  node_analysis_hook["Analysis state<br/>[useAnalysis.js]"]
  node_api_client["API client<br/>[client.js]"]
  node_api_mock["Mock API<br/>[mock.js]"]
  node_results["Result display<br/>[ResultView.jsx]"]
  node_session["Session summary<br/>[SessionPage.jsx]"]
  node_session_state["Session state<br/>[useSession.js]"]
  node_session_charts["Session charts<br/>[TrustScoreBars.jsx]"]
end

subgraph group_api["Analysis API"]
  node_backend["FastAPI app<br/>[main.py]"]
  node_routes["Analysis routes<br/>[routes.py]"]
  node_validation["Request schemas<br/>[schemas.py]"]
  node_middleware["Request middleware<br/>[middleware.py]"]
  node_rate_limit["Rate limiting<br/>[rate_limit.py]"]
  node_errors["Error handling<br/>[errors.py]"]
end

subgraph group_scoring["Scoring engine"]
  node_model_service["Model service<br/>[model_service.py]"]
  node_normalization["URL normalization<br/>[normalization.py]"]
  node_rules["Rule signals<br/>[rules.py]"]
  node_explanations["Score explanations<br/>[explanations.py]"]
  node_a2_bridge["A2 feature bridge<br/>[a2.py]"]
  node_brand_data["Brand reference<br/>[brand_list.py]"]
  node_model_artifact[("Verified model artifact")]
end

subgraph group_training["Model pipeline"]
  node_features["Feature extraction"]
  node_training_script["Model training<br/>[train_model.py]"]
end

node_browser(("Browser user"))

node_browser -->|"submits URL"| node_home
node_app -->|"routes to"| node_home
node_app -->|"routes to"| node_session
node_home -->|"runs analysis"| node_analysis_hook
node_analysis_hook -->|"requests analysis"| node_api_client
node_api_client -->|"POSTs URL"| node_backend
node_api_client -->|"selects mock"| node_api_mock
node_home -->|"renders result"| node_results
node_home -->|"records result"| node_session_state
node_session -->|"reads checks"| node_session_state
node_session -->|"renders charts"| node_session_charts
node_backend -->|"registers routes"| node_routes
node_backend -->|"installs middleware"| node_middleware
node_backend -->|"configures limiter"| node_rate_limit
node_backend -->|"loads service"| node_model_service
node_backend -->|"installs handlers"| node_errors
node_routes -->|"validates payload"| node_validation
node_routes -->|"runs analysis"| node_model_service
node_model_service -->|"normalizes text"| node_normalization
node_model_service -->|"gets rule signals"| node_rules
node_model_service -->|"gets n-gram signals"| node_explanations
node_model_service -->|"uses A2 features"| node_a2_bridge
node_a2_bridge -->|"imports feature code"| node_features
node_features -->|"uses brand reference"| node_brand_data
node_model_service -->|"loads verified model"| node_model_artifact
node_training_script -.->|"uses feature pipeline"| node_features
node_training_script -.->|"trains model"| node_model_artifact

click node_app "https://github.com/ducvovn01/phishing_url_project/blob/main/frontend/src/App.jsx"
click node_home "https://github.com/ducvovn01/phishing_url_project/blob/main/frontend/src/pages/HomePage.jsx"
click node_analysis_hook "https://github.com/ducvovn01/phishing_url_project/blob/main/frontend/src/hooks/useAnalysis.js"
click node_api_client "https://github.com/ducvovn01/phishing_url_project/blob/main/frontend/src/api/client.js"
click node_api_mock "https://github.com/ducvovn01/phishing_url_project/blob/main/frontend/src/api/mock.js"
click node_results "https://github.com/ducvovn01/phishing_url_project/blob/main/frontend/src/components/results/ResultView.jsx"
click node_session "https://github.com/ducvovn01/phishing_url_project/blob/main/frontend/src/pages/SessionPage.jsx"
click node_session_state "https://github.com/ducvovn01/phishing_url_project/blob/main/frontend/src/session/useSession.js"
click node_session_charts "https://github.com/ducvovn01/phishing_url_project/blob/main/frontend/src/components/session/TrustScoreBars.jsx"
click node_backend "https://github.com/ducvovn01/phishing_url_project/blob/main/backend/app/main.py"
click node_routes "https://github.com/ducvovn01/phishing_url_project/blob/main/backend/app/routes.py"
click node_validation "https://github.com/ducvovn01/phishing_url_project/blob/main/backend/app/schemas.py"
click node_middleware "https://github.com/ducvovn01/phishing_url_project/blob/main/backend/app/middleware.py"
click node_rate_limit "https://github.com/ducvovn01/phishing_url_project/blob/main/backend/app/rate_limit.py"
click node_errors "https://github.com/ducvovn01/phishing_url_project/blob/main/backend/app/errors.py"
click node_model_service "https://github.com/ducvovn01/phishing_url_project/blob/main/backend/app/services/model_service.py"
click node_normalization "https://github.com/ducvovn01/phishing_url_project/blob/main/backend/app/services/normalization.py"
click node_rules "https://github.com/ducvovn01/phishing_url_project/blob/main/backend/app/services/rules.py"
click node_explanations "https://github.com/ducvovn01/phishing_url_project/blob/main/backend/app/services/explanations.py"
click node_a2_bridge "https://github.com/ducvovn01/phishing_url_project/blob/main/backend/app/a2.py"
click node_brand_data "https://github.com/ducvovn01/phishing_url_project/blob/main/data/reference/brand_list.py"
click node_features "https://github.com/ducvovn01/phishing_url_project/blob/main/scripts/extract_features.py"
click node_training_script "https://github.com/ducvovn01/phishing_url_project/blob/main/scripts/train_model.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_app,node_home,node_analysis_hook,node_api_client,node_api_mock,node_results,node_session,node_session_state,node_session_charts,node_browser toneBlue
class node_backend,node_routes,node_validation,node_middleware,node_rate_limit,node_errors toneAmber
class node_model_service,node_normalization,node_rules,node_explanations,node_a2_bridge,node_brand_data,node_model_artifact toneMint
class node_features,node_training_script toneRose
```

## Components

### Web client

- [App routes](https://github.com/ducvovn01/phishing_url_project/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [URL checker](https://github.com/ducvovn01/phishing_url_project/blob/main/frontend/src/pages/HomePage.jsx): `frontend/src/pages/HomePage.jsx`
- [Analysis state](https://github.com/ducvovn01/phishing_url_project/blob/main/frontend/src/hooks/useAnalysis.js): `frontend/src/hooks/useAnalysis.js`
- [API client](https://github.com/ducvovn01/phishing_url_project/blob/main/frontend/src/api/client.js): `frontend/src/api/client.js`
- [Mock API](https://github.com/ducvovn01/phishing_url_project/blob/main/frontend/src/api/mock.js): `frontend/src/api/mock.js`
- [Result display](https://github.com/ducvovn01/phishing_url_project/blob/main/frontend/src/components/results/ResultView.jsx): `frontend/src/components/results/ResultView.jsx`
- [Session summary](https://github.com/ducvovn01/phishing_url_project/blob/main/frontend/src/pages/SessionPage.jsx): `frontend/src/pages/SessionPage.jsx`
- [Session state](https://github.com/ducvovn01/phishing_url_project/blob/main/frontend/src/session/useSession.js): `frontend/src/session/useSession.js`
- [Session charts](https://github.com/ducvovn01/phishing_url_project/blob/main/frontend/src/components/session/TrustScoreBars.jsx): `frontend/src/components/session/TrustScoreBars.jsx`

### Analysis API

- [FastAPI app](https://github.com/ducvovn01/phishing_url_project/blob/main/backend/app/main.py): `backend/app/main.py`
- [Analysis routes](https://github.com/ducvovn01/phishing_url_project/blob/main/backend/app/routes.py): `backend/app/routes.py`
- [Request schemas](https://github.com/ducvovn01/phishing_url_project/blob/main/backend/app/schemas.py): `backend/app/schemas.py`
- [Request middleware](https://github.com/ducvovn01/phishing_url_project/blob/main/backend/app/middleware.py): `backend/app/middleware.py`
- [Rate limiting](https://github.com/ducvovn01/phishing_url_project/blob/main/backend/app/rate_limit.py): `backend/app/rate_limit.py`
- [Error handling](https://github.com/ducvovn01/phishing_url_project/blob/main/backend/app/errors.py): `backend/app/errors.py`

### Scoring engine

- [Model service](https://github.com/ducvovn01/phishing_url_project/blob/main/backend/app/services/model_service.py): `backend/app/services/model_service.py`
- [URL normalization](https://github.com/ducvovn01/phishing_url_project/blob/main/backend/app/services/normalization.py): `backend/app/services/normalization.py`
- [Rule signals](https://github.com/ducvovn01/phishing_url_project/blob/main/backend/app/services/rules.py): `backend/app/services/rules.py`
- [Score explanations](https://github.com/ducvovn01/phishing_url_project/blob/main/backend/app/services/explanations.py): `backend/app/services/explanations.py`
- [A2 feature bridge](https://github.com/ducvovn01/phishing_url_project/blob/main/backend/app/a2.py): `backend/app/a2.py`
- [Brand reference](https://github.com/ducvovn01/phishing_url_project/blob/main/data/reference/brand_list.py): `data/reference/brand_list.py`
- **Verified model artifact**

### Model pipeline

- [Feature extraction](https://github.com/ducvovn01/phishing_url_project/blob/main/scripts/extract_features.py): `scripts/extract_features.py`
- [Model training](https://github.com/ducvovn01/phishing_url_project/blob/main/scripts/train_model.py): `scripts/train_model.py`

### Other components

- **Browser user**

## Connections

- Browser user → URL checker: submits URL (evidence: `README.md`)
- App routes → URL checker: routes to (evidence: `frontend/src/App.jsx`)
- App routes → Session summary: routes to (evidence: `frontend/src/App.jsx`)
- URL checker → Analysis state: runs analysis (evidence: `frontend/src/pages/HomePage.jsx`)
- Analysis state → API client: requests analysis (evidence: `frontend/src/hooks/useAnalysis.js`)
- API client → FastAPI app: POSTs URL (evidence: `README.md`)
- API client → Mock API: selects mock (evidence: `frontend/src/api/index.js`)
- URL checker → Result display: renders result (evidence: `frontend/src/pages/HomePage.jsx`)
- URL checker → Session state: records result (evidence: `frontend/src/pages/HomePage.jsx`)
- Session summary → Session state: reads checks (evidence: `frontend/src/pages/SessionPage.jsx`)
- Session summary → Session charts: renders charts (evidence: `frontend/src/pages/SessionPage.jsx`)
- FastAPI app → Analysis routes: registers routes (evidence: `backend/app/main.py`)
- FastAPI app → Request middleware: installs middleware (evidence: `backend/app/main.py`)
- FastAPI app → Rate limiting: configures limiter (evidence: `backend/app/main.py`)
- FastAPI app → Model service: loads service (evidence: `backend/app/main.py`)
- FastAPI app → Error handling: installs handlers (evidence: `backend/app/main.py`)
- Analysis routes → Request schemas: validates payload (evidence: `backend/app/routes.py`)
- Analysis routes → Model service: runs analysis (evidence: `backend/app/routes.py`)
- Model service → URL normalization: normalizes text (evidence: `backend/app/services/model_service.py`)
- Model service → Rule signals: gets rule signals (evidence: `backend/app/services/model_service.py`)
- Model service → Score explanations: gets n-gram signals (evidence: `backend/app/services/model_service.py`)
- Model service → A2 feature bridge: uses A2 features (evidence: `backend/app/services/model_service.py`)
- A2 feature bridge → Feature extraction: imports feature code (evidence: `backend/app/a2.py`)
- Feature extraction → Brand reference: uses brand reference (evidence: `data/reference/brand_list.py`)
- Model service → Verified model artifact: loads verified model (evidence: `README.md`)
- Model training → Feature extraction: uses feature pipeline
- Model training → Verified model artifact: trains model (evidence: `README.md`)