# balavishnu437-ai/phishguard architecture

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

- Interactive diagram: https://gitdiagram.com/balavishnu437-ai/phishguard
- Repository: https://github.com/balavishnu437-ai/phishguard

## Overview

PhishGuard accepts a URL through its web scanner, sends it to the FastAPI service, extracts URL and page features, applies a trained classifier plus safety overrides, and returns a verdict for presentation. The API also exposes scan history, statistics, and threat-intelligence capabilities; the React application includes scanning, dashboard, history, and threat-analysis views. The README documents REST and persistence behavior. Some route-to-storage and page-to-API wiring is unsampled, so those documented connections are marked dashed.

Main entry points: [`backend/server.py`](https://github.com/balavishnu437-ai/phishguard/blob/main/backend/server.py) (FastAPI Service), [`frontend/src/pages/ThreatIntel.jsx`](https://github.com/balavishnu437-ai/phishguard/blob/main/frontend/src/pages/ThreatIntel.jsx) (Threat Intel View), [`frontend/src/App.js`](https://github.com/balavishnu437-ai/phishguard/blob/main/frontend/src/App.js) (React App Router), [`backend/predictor.py`](https://github.com/balavishnu437-ai/phishguard/blob/main/backend/predictor.py) (Prediction and Overrides)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web Application"]
  node_app["React App Router<br/>[App.js]"]
  node_scanner["URL Scanner<br/>[Scanner.jsx]"]
  node_results["Verdict Presentation<br/>[ResultCard.jsx]"]
  node_dashboard["Threat Dashboard<br/>[Dashboard.jsx]"]
  node_history["Scan History View<br/>[History.jsx]"]
  node_intelpage["Threat Intel View<br/>[ThreatIntel.jsx]"]
end

subgraph group_api["API and Persistence"]
  node_api["FastAPI Service<br/>[server.py]"]
  node_mongo[("MongoDB")]
  node_localstore[("Local JSON Fallback<br/>[.data]")]
end

subgraph group_analysis["Detection Engine"]
  node_predictor["Prediction and Overrides<br/>[predictor.py]"]
  node_features["Feature Extraction"]
  node_utils["URL Validation and Risk<br/>[utils.py]"]
  node_model["Decision Tree Pipeline"]
end

subgraph group_intel["Threat Intelligence"]
  node_forensics["URL Forensics<br/>[URLForensics.jsx]"]
  node_riskmeter["Threat Risk Meter"]
  node_intelcards["MITRE Intel Cards"]
  node_recommendations["Security Recommendations"]
  node_threatmap["Live Threat Map<br/>[LiveThreatMap.jsx]"]
  node_timeline["Threat Timeline"]
end

node_analyst(("User / Analyst"))

node_analyst -->|"uses"| node_app
node_app -->|"routes"| node_scanner
node_app -->|"routes"| node_dashboard
node_app -->|"routes"| node_history
node_app -->|"routes"| node_intelpage
node_scanner -.->|"submits URL"| node_api
node_api -->|"invokes scan"| node_predictor
node_predictor -->|"extracts features"| node_features
node_predictor -.->|"classifies features"| node_model
node_predictor -->|"validates and scores"| node_utils
node_api -.->|"persists records"| node_mongo
node_api -.->|"falls back to"| node_localstore
node_api -.->|"returns verdict"| node_scanner
node_scanner -.->|"presents result"| node_results
node_dashboard -.->|"requests statistics"| node_api
node_history -.->|"requests history"| node_api
node_intelpage -.->|"presents forensics"| node_forensics
node_intelpage -.->|"presents risk"| node_riskmeter
node_intelpage -.->|"presents intel"| node_intelcards
node_intelpage -.->|"presents guidance"| node_recommendations
node_intelpage -.->|"presents map"| node_threatmap
node_history -.->|"presents timeline"| node_timeline

click node_app "https://github.com/balavishnu437-ai/phishguard/blob/main/frontend/src/App.js"
click node_scanner "https://github.com/balavishnu437-ai/phishguard/blob/main/frontend/src/pages/Scanner.jsx"
click node_results "https://github.com/balavishnu437-ai/phishguard/blob/main/frontend/src/components/ResultCard.jsx"
click node_dashboard "https://github.com/balavishnu437-ai/phishguard/blob/main/frontend/src/pages/Dashboard.jsx"
click node_history "https://github.com/balavishnu437-ai/phishguard/blob/main/frontend/src/pages/History.jsx"
click node_intelpage "https://github.com/balavishnu437-ai/phishguard/blob/main/frontend/src/pages/ThreatIntel.jsx"
click node_api "https://github.com/balavishnu437-ai/phishguard/blob/main/backend/server.py"
click node_localstore "https://github.com/balavishnu437-ai/phishguard/tree/main/backend/.data"
click node_predictor "https://github.com/balavishnu437-ai/phishguard/blob/main/backend/predictor.py"
click node_features "https://github.com/balavishnu437-ai/phishguard/blob/main/backend/feature_extractor.py"
click node_utils "https://github.com/balavishnu437-ai/phishguard/blob/main/backend/utils.py"
click node_model "https://github.com/balavishnu437-ai/phishguard/blob/main/backend/models/phishing_decision_tree_pipeline.pkl"
click node_forensics "https://github.com/balavishnu437-ai/phishguard/blob/main/frontend/src/components/URLForensics.jsx"
click node_riskmeter "https://github.com/balavishnu437-ai/phishguard/blob/main/frontend/src/components/ThreatRiskMeter.jsx"
click node_intelcards "https://github.com/balavishnu437-ai/phishguard/blob/main/frontend/src/components/ThreatIntelCards.jsx"
click node_recommendations "https://github.com/balavishnu437-ai/phishguard/blob/main/frontend/src/components/SecurityRecommendations.jsx"
click node_threatmap "https://github.com/balavishnu437-ai/phishguard/blob/main/frontend/src/components/LiveThreatMap.jsx"
click node_timeline "https://github.com/balavishnu437-ai/phishguard/blob/main/frontend/src/components/ThreatHistoryTimeline.jsx"

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_scanner,node_results,node_dashboard,node_history,node_intelpage,node_analyst toneBlue
class node_api,node_mongo,node_localstore toneAmber
class node_predictor,node_features,node_utils,node_model toneMint
class node_forensics,node_riskmeter,node_intelcards,node_recommendations,node_threatmap,node_timeline toneRose
```

## Components

### Web Application

- [React App Router](https://github.com/balavishnu437-ai/phishguard/blob/main/frontend/src/App.js): `frontend/src/App.js`
- [URL Scanner](https://github.com/balavishnu437-ai/phishguard/blob/main/frontend/src/pages/Scanner.jsx): `frontend/src/pages/Scanner.jsx`
- [Verdict Presentation](https://github.com/balavishnu437-ai/phishguard/blob/main/frontend/src/components/ResultCard.jsx): `frontend/src/components/ResultCard.jsx`
- [Threat Dashboard](https://github.com/balavishnu437-ai/phishguard/blob/main/frontend/src/pages/Dashboard.jsx): `frontend/src/pages/Dashboard.jsx`
- [Scan History View](https://github.com/balavishnu437-ai/phishguard/blob/main/frontend/src/pages/History.jsx): `frontend/src/pages/History.jsx`
- [Threat Intel View](https://github.com/balavishnu437-ai/phishguard/blob/main/frontend/src/pages/ThreatIntel.jsx): `frontend/src/pages/ThreatIntel.jsx`

### API and Persistence

- [FastAPI Service](https://github.com/balavishnu437-ai/phishguard/blob/main/backend/server.py): `backend/server.py`
- **MongoDB**
- [Local JSON Fallback](https://github.com/balavishnu437-ai/phishguard/tree/main/backend/.data): `backend/.data`

### Detection Engine

- [Prediction and Overrides](https://github.com/balavishnu437-ai/phishguard/blob/main/backend/predictor.py): `backend/predictor.py`
- [Feature Extraction](https://github.com/balavishnu437-ai/phishguard/blob/main/backend/feature_extractor.py): `backend/feature_extractor.py`
- [URL Validation and Risk](https://github.com/balavishnu437-ai/phishguard/blob/main/backend/utils.py): `backend/utils.py`
- [Decision Tree Pipeline](https://github.com/balavishnu437-ai/phishguard/blob/main/backend/models/phishing_decision_tree_pipeline.pkl): `backend/models/phishing_decision_tree_pipeline.pkl`

### Threat Intelligence

- [URL Forensics](https://github.com/balavishnu437-ai/phishguard/blob/main/frontend/src/components/URLForensics.jsx): `frontend/src/components/URLForensics.jsx`
- [Threat Risk Meter](https://github.com/balavishnu437-ai/phishguard/blob/main/frontend/src/components/ThreatRiskMeter.jsx): `frontend/src/components/ThreatRiskMeter.jsx`
- [MITRE Intel Cards](https://github.com/balavishnu437-ai/phishguard/blob/main/frontend/src/components/ThreatIntelCards.jsx): `frontend/src/components/ThreatIntelCards.jsx`
- [Security Recommendations](https://github.com/balavishnu437-ai/phishguard/blob/main/frontend/src/components/SecurityRecommendations.jsx): `frontend/src/components/SecurityRecommendations.jsx`
- [Live Threat Map](https://github.com/balavishnu437-ai/phishguard/blob/main/frontend/src/components/LiveThreatMap.jsx): `frontend/src/components/LiveThreatMap.jsx`
- [Threat Timeline](https://github.com/balavishnu437-ai/phishguard/blob/main/frontend/src/components/ThreatHistoryTimeline.jsx): `frontend/src/components/ThreatHistoryTimeline.jsx`

### Other components

- **User / Analyst**

## Connections

- User / Analyst → React App Router: uses (evidence: `README.md`)
- React App Router → URL Scanner: routes (evidence: `frontend/src/App.js`)
- React App Router → Threat Dashboard: routes (evidence: `frontend/src/App.js`)
- React App Router → Scan History View: routes (evidence: `frontend/src/App.js`)
- React App Router → Threat Intel View: routes (evidence: `frontend/src/App.js`)
- URL Scanner → FastAPI Service: submits URL (evidence: `README.md`)
- FastAPI Service → Prediction and Overrides: invokes scan (evidence: `backend/server.py`)
- Prediction and Overrides → Feature Extraction: extracts features (evidence: `backend/predictor.py`)
- Prediction and Overrides → Decision Tree Pipeline: classifies features (evidence: `README.md`)
- Prediction and Overrides → URL Validation and Risk: validates and scores (evidence: `backend/predictor.py`)
- FastAPI Service → MongoDB: persists records (evidence: `README.md`)
- FastAPI Service → Local JSON Fallback: falls back to (evidence: `README.md`)
- FastAPI Service → URL Scanner: returns verdict (evidence: `README.md`)
- URL Scanner → Verdict Presentation: presents result
- Threat Dashboard → FastAPI Service: requests statistics (evidence: `README.md`)
- Scan History View → FastAPI Service: requests history (evidence: `README.md`)
- Threat Intel View → URL Forensics: presents forensics (evidence: `README.md`)
- Threat Intel View → Threat Risk Meter: presents risk (evidence: `README.md`)
- Threat Intel View → MITRE Intel Cards: presents intel (evidence: `README.md`)
- Threat Intel View → Security Recommendations: presents guidance (evidence: `README.md`)
- Threat Intel View → Live Threat Map: presents map (evidence: `README.md`)
- Scan History View → Threat Timeline: presents timeline (evidence: `README.md`)