# bipeen-ranjan/nlp-lexical-ai-qr-phishing-detection architecture

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

- Interactive diagram: https://gitdiagram.com/bipeen-ranjan/nlp-lexical-ai-qr-phishing-detection
- Repository: https://github.com/bipeen-ranjan/nlp-lexical-ai-qr-phishing-detection

## Overview

QPhish Guardian is a pre-click QR and URL phishing analysis platform. Users submit a QR image or decoded payload; the documented detection flow analyzes URL structure and payload characteristics, classifies risk, checks threat intelligence, applies a risk policy, and presents an explainable verdict. The backend also provides accounts, scan records, dashboards, administration, and PDF reports, while a browser extension detects QR codes on pages. The detection stages are documented in the README; backend scan-service connections are supported by the scan router’s source-index references, but many UI-to-API details were not sampled.

Main entry points: [`backend/app/main.py`](https://github.com/bipeen-ranjan/nlp-lexical-ai-qr-phishing-detection/blob/main/backend/app/main.py) (API Router), [`backend/app/routers/scan.py`](https://github.com/bipeen-ranjan/nlp-lexical-ai-qr-phishing-detection/blob/main/backend/app/routers/scan.py) (Scan Endpoint), [`frontend/src/App.tsx`](https://github.com/bipeen-ranjan/nlp-lexical-ai-qr-phishing-detection/blob/main/frontend/src/App.tsx) (Web Application), [`backend/app/database.py`](https://github.com/bipeen-ranjan/nlp-lexical-ai-qr-phishing-detection/blob/main/backend/app/database.py) (Application Database)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["User Clients"]
  node_webapp["Web Application<br/>[App.tsx]"]
  node_auth_ui["Session Context<br/>[AuthContext.tsx]"]
  node_scan_ui["QR Scan UI<br/>[ScanQR.tsx]"]
  node_extension["Browser Extension<br/>[content.js]"]
  node_dashboard_ui["Dashboard &amp; Analytics<br/>[Dashboard.tsx]"]
  node_history_ui["History View<br/>[History.tsx]"]
  node_analytics_ui["Analytics View<br/>[Analytics.tsx]"]
  node_admin_ui["Admin View<br/>[Admin.tsx]"]
end

subgraph group_analysis["Threat Analysis"]
  node_scan_route["Scan Endpoint<br/>[scan.py]"]
  node_qr_decode["QR Decoding<br/>[qr_service.py]"]
  node_payload_analysis["Payload Analysis"]
  node_lexical["Lexical Features<br/>[lexical_service.py]"]
  node_ml["ML Classification<br/>[ml_service.py]"]
  node_feature_engineering["Model Features<br/>[qphish_features.py]"]
  node_threat_intel["Threat Intelligence"]
  node_risk_policy["Risk Policy"]
end

subgraph group_platform["Platform Services"]
  node_api["API Router<br/>[main.py]"]
  node_auth_api["Authentication<br/>[auth.py]"]
  node_auth_core["JWT &amp; Access Control<br/>[auth.py]"]
  node_models["Domain Models<br/>[models.py]"]
  node_database[("Application Database<br/>[database.py]")]
end

subgraph group_insights["History &amp; Insights"]
  node_dashboard["Dashboard Stats<br/>[dashboard.py]"]
  node_history["Scan History<br/>[history.py]"]
  node_admin["Administration<br/>[admin.py]"]
  node_reports["PDF Reports<br/>[reports.py]"]
  node_pdf["PDF Generation<br/>[pdf_service.py]"]
end

node_user(("User"))

node_user -->|"uses"| node_webapp
node_webapp -->|"provides session"| node_auth_ui
node_webapp -->|"routes to"| node_scan_ui
node_user -->|"scans page"| node_extension
node_extension -.->|"submits payload"| node_api
node_scan_ui -.->|"requests analysis"| node_api
node_api -->|"routes scans"| node_scan_route
node_api -->|"routes auth"| node_auth_api
node_api -->|"routes stats"| node_dashboard
node_api -->|"routes history"| node_history
node_api -->|"routes admin"| node_admin
node_api -->|"routes reports"| node_reports
node_scan_route -->|"decodes QR"| node_qr_decode
node_scan_route -->|"analyzes payload"| node_payload_analysis
node_scan_route -->|"extracts features"| node_lexical
node_scan_route -->|"classifies URL"| node_ml
node_ml -->|"featurizes URL"| node_feature_engineering
node_scan_route -->|"checks reputation"| node_threat_intel
node_scan_route -->|"sets risk"| node_risk_policy
node_scan_route -->|"persists scan"| node_database
node_scan_route -->|"records results"| node_models
node_auth_api -->|"authenticates"| node_auth_core
node_auth_api -->|"reads users"| node_database
node_auth_core -->|"loads user"| node_database
node_dashboard -->|"queries scans"| node_database
node_history -->|"queries scans"| node_database
node_admin -->|"queries records"| node_database
node_reports -->|"generates report"| node_pdf
node_reports -->|"loads scan data"| node_database
node_webapp -->|"routes to"| node_dashboard_ui
node_webapp -->|"routes to"| node_history_ui
node_webapp -->|"routes to"| node_analytics_ui
node_webapp -->|"routes to"| node_admin_ui
node_dashboard_ui -.->|"loads insights"| node_api
node_history_ui -.->|"loads scans"| node_api
node_analytics_ui -.->|"loads analytics"| node_api
node_admin_ui -.->|"requests admin"| node_api

click node_webapp "https://github.com/bipeen-ranjan/nlp-lexical-ai-qr-phishing-detection/blob/main/frontend/src/App.tsx"
click node_auth_ui "https://github.com/bipeen-ranjan/nlp-lexical-ai-qr-phishing-detection/blob/main/frontend/src/context/AuthContext.tsx"
click node_scan_ui "https://github.com/bipeen-ranjan/nlp-lexical-ai-qr-phishing-detection/blob/main/frontend/src/pages/ScanQR.tsx"
click node_extension "https://github.com/bipeen-ranjan/nlp-lexical-ai-qr-phishing-detection/blob/main/extension/content.js"
click node_api "https://github.com/bipeen-ranjan/nlp-lexical-ai-qr-phishing-detection/blob/main/backend/app/main.py"
click node_scan_route "https://github.com/bipeen-ranjan/nlp-lexical-ai-qr-phishing-detection/blob/main/backend/app/routers/scan.py"
click node_qr_decode "https://github.com/bipeen-ranjan/nlp-lexical-ai-qr-phishing-detection/blob/main/backend/app/services/qr_service.py"
click node_payload_analysis "https://github.com/bipeen-ranjan/nlp-lexical-ai-qr-phishing-detection/blob/main/backend/app/services/qr_payload_service.py"
click node_lexical "https://github.com/bipeen-ranjan/nlp-lexical-ai-qr-phishing-detection/blob/main/backend/app/services/lexical_service.py"
click node_ml "https://github.com/bipeen-ranjan/nlp-lexical-ai-qr-phishing-detection/blob/main/backend/app/services/ml_service.py"
click node_feature_engineering "https://github.com/bipeen-ranjan/nlp-lexical-ai-qr-phishing-detection/blob/main/ml/qphish_features.py"
click node_threat_intel "https://github.com/bipeen-ranjan/nlp-lexical-ai-qr-phishing-detection/blob/main/backend/app/services/threat_intel_service.py"
click node_risk_policy "https://github.com/bipeen-ranjan/nlp-lexical-ai-qr-phishing-detection/blob/main/backend/app/services/risk_policy_service.py"
click node_auth_api "https://github.com/bipeen-ranjan/nlp-lexical-ai-qr-phishing-detection/blob/main/backend/app/routers/auth.py"
click node_auth_core "https://github.com/bipeen-ranjan/nlp-lexical-ai-qr-phishing-detection/blob/main/backend/app/auth.py"
click node_models "https://github.com/bipeen-ranjan/nlp-lexical-ai-qr-phishing-detection/blob/main/backend/app/models.py"
click node_database "https://github.com/bipeen-ranjan/nlp-lexical-ai-qr-phishing-detection/blob/main/backend/app/database.py"
click node_dashboard "https://github.com/bipeen-ranjan/nlp-lexical-ai-qr-phishing-detection/blob/main/backend/app/routers/dashboard.py"
click node_history "https://github.com/bipeen-ranjan/nlp-lexical-ai-qr-phishing-detection/blob/main/backend/app/routers/history.py"
click node_admin "https://github.com/bipeen-ranjan/nlp-lexical-ai-qr-phishing-detection/blob/main/backend/app/routers/admin.py"
click node_reports "https://github.com/bipeen-ranjan/nlp-lexical-ai-qr-phishing-detection/blob/main/backend/app/routers/reports.py"
click node_pdf "https://github.com/bipeen-ranjan/nlp-lexical-ai-qr-phishing-detection/blob/main/backend/app/services/pdf_service.py"
click node_dashboard_ui "https://github.com/bipeen-ranjan/nlp-lexical-ai-qr-phishing-detection/blob/main/frontend/src/pages/Dashboard.tsx"
click node_history_ui "https://github.com/bipeen-ranjan/nlp-lexical-ai-qr-phishing-detection/blob/main/frontend/src/pages/History.tsx"
click node_analytics_ui "https://github.com/bipeen-ranjan/nlp-lexical-ai-qr-phishing-detection/blob/main/frontend/src/pages/Analytics.tsx"
click node_admin_ui "https://github.com/bipeen-ranjan/nlp-lexical-ai-qr-phishing-detection/blob/main/frontend/src/pages/Admin.tsx"

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_webapp,node_auth_ui,node_scan_ui,node_extension,node_dashboard_ui,node_history_ui,node_analytics_ui,node_admin_ui,node_user toneBlue
class node_scan_route,node_qr_decode,node_payload_analysis,node_lexical,node_ml,node_feature_engineering,node_threat_intel,node_risk_policy toneAmber
class node_api,node_auth_api,node_auth_core,node_models,node_database toneMint
class node_dashboard,node_history,node_admin,node_reports,node_pdf toneRose
```

## Components

### User Clients

- [Web Application](https://github.com/bipeen-ranjan/nlp-lexical-ai-qr-phishing-detection/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Session Context](https://github.com/bipeen-ranjan/nlp-lexical-ai-qr-phishing-detection/blob/main/frontend/src/context/AuthContext.tsx): `frontend/src/context/AuthContext.tsx`
- [QR Scan UI](https://github.com/bipeen-ranjan/nlp-lexical-ai-qr-phishing-detection/blob/main/frontend/src/pages/ScanQR.tsx): `frontend/src/pages/ScanQR.tsx`
- [Browser Extension](https://github.com/bipeen-ranjan/nlp-lexical-ai-qr-phishing-detection/blob/main/extension/content.js): `extension/content.js`
- [Dashboard & Analytics](https://github.com/bipeen-ranjan/nlp-lexical-ai-qr-phishing-detection/blob/main/frontend/src/pages/Dashboard.tsx): `frontend/src/pages/Dashboard.tsx`
- [History View](https://github.com/bipeen-ranjan/nlp-lexical-ai-qr-phishing-detection/blob/main/frontend/src/pages/History.tsx): `frontend/src/pages/History.tsx`
- [Analytics View](https://github.com/bipeen-ranjan/nlp-lexical-ai-qr-phishing-detection/blob/main/frontend/src/pages/Analytics.tsx): `frontend/src/pages/Analytics.tsx`
- [Admin View](https://github.com/bipeen-ranjan/nlp-lexical-ai-qr-phishing-detection/blob/main/frontend/src/pages/Admin.tsx): `frontend/src/pages/Admin.tsx`

### Threat Analysis

- [Scan Endpoint](https://github.com/bipeen-ranjan/nlp-lexical-ai-qr-phishing-detection/blob/main/backend/app/routers/scan.py): `backend/app/routers/scan.py`
- [QR Decoding](https://github.com/bipeen-ranjan/nlp-lexical-ai-qr-phishing-detection/blob/main/backend/app/services/qr_service.py): `backend/app/services/qr_service.py`
- [Payload Analysis](https://github.com/bipeen-ranjan/nlp-lexical-ai-qr-phishing-detection/blob/main/backend/app/services/qr_payload_service.py): `backend/app/services/qr_payload_service.py`
- [Lexical Features](https://github.com/bipeen-ranjan/nlp-lexical-ai-qr-phishing-detection/blob/main/backend/app/services/lexical_service.py): `backend/app/services/lexical_service.py`
- [ML Classification](https://github.com/bipeen-ranjan/nlp-lexical-ai-qr-phishing-detection/blob/main/backend/app/services/ml_service.py): `backend/app/services/ml_service.py`
- [Model Features](https://github.com/bipeen-ranjan/nlp-lexical-ai-qr-phishing-detection/blob/main/ml/qphish_features.py): `ml/qphish_features.py`
- [Threat Intelligence](https://github.com/bipeen-ranjan/nlp-lexical-ai-qr-phishing-detection/blob/main/backend/app/services/threat_intel_service.py): `backend/app/services/threat_intel_service.py`
- [Risk Policy](https://github.com/bipeen-ranjan/nlp-lexical-ai-qr-phishing-detection/blob/main/backend/app/services/risk_policy_service.py): `backend/app/services/risk_policy_service.py`

### Platform Services

- [API Router](https://github.com/bipeen-ranjan/nlp-lexical-ai-qr-phishing-detection/blob/main/backend/app/main.py): `backend/app/main.py`
- [Authentication](https://github.com/bipeen-ranjan/nlp-lexical-ai-qr-phishing-detection/blob/main/backend/app/routers/auth.py): `backend/app/routers/auth.py`
- [JWT & Access Control](https://github.com/bipeen-ranjan/nlp-lexical-ai-qr-phishing-detection/blob/main/backend/app/auth.py): `backend/app/auth.py`
- [Domain Models](https://github.com/bipeen-ranjan/nlp-lexical-ai-qr-phishing-detection/blob/main/backend/app/models.py): `backend/app/models.py`
- [Application Database](https://github.com/bipeen-ranjan/nlp-lexical-ai-qr-phishing-detection/blob/main/backend/app/database.py): `backend/app/database.py`

### History & Insights

- [Dashboard Stats](https://github.com/bipeen-ranjan/nlp-lexical-ai-qr-phishing-detection/blob/main/backend/app/routers/dashboard.py): `backend/app/routers/dashboard.py`
- [Scan History](https://github.com/bipeen-ranjan/nlp-lexical-ai-qr-phishing-detection/blob/main/backend/app/routers/history.py): `backend/app/routers/history.py`
- [Administration](https://github.com/bipeen-ranjan/nlp-lexical-ai-qr-phishing-detection/blob/main/backend/app/routers/admin.py): `backend/app/routers/admin.py`
- [PDF Reports](https://github.com/bipeen-ranjan/nlp-lexical-ai-qr-phishing-detection/blob/main/backend/app/routers/reports.py): `backend/app/routers/reports.py`
- [PDF Generation](https://github.com/bipeen-ranjan/nlp-lexical-ai-qr-phishing-detection/blob/main/backend/app/services/pdf_service.py): `backend/app/services/pdf_service.py`

### Other components

- **User**

## Connections

- User → Web Application: uses (evidence: `frontend/src/App.tsx`)
- Web Application → Session Context: provides session (evidence: `frontend/src/App.tsx`)
- Web Application → QR Scan UI: routes to (evidence: `frontend/src/App.tsx`)
- User → Browser Extension: scans page
- Browser Extension → API Router: submits payload
- QR Scan UI → API Router: requests analysis
- API Router → Scan Endpoint: routes scans (evidence: `backend/app/main.py`)
- API Router → Authentication: routes auth (evidence: `backend/app/main.py`)
- API Router → Dashboard Stats: routes stats (evidence: `backend/app/main.py`)
- API Router → Scan History: routes history (evidence: `backend/app/main.py`)
- API Router → Administration: routes admin (evidence: `backend/app/main.py`)
- API Router → PDF Reports: routes reports (evidence: `backend/app/main.py`)
- Scan Endpoint → QR Decoding: decodes QR (evidence: `backend/app/routers/scan.py`)
- Scan Endpoint → Payload Analysis: analyzes payload (evidence: `backend/app/routers/scan.py`)
- Scan Endpoint → Lexical Features: extracts features (evidence: `backend/app/routers/scan.py`)
- Scan Endpoint → ML Classification: classifies URL (evidence: `backend/app/routers/scan.py`)
- ML Classification → Model Features: featurizes URL (evidence: `backend/app/services/ml_service.py`)
- Scan Endpoint → Threat Intelligence: checks reputation (evidence: `backend/app/routers/scan.py`)
- Scan Endpoint → Risk Policy: sets risk (evidence: `backend/app/routers/scan.py`)
- Scan Endpoint → Application Database: persists scan (evidence: `backend/app/routers/scan.py`)
- Scan Endpoint → Domain Models: records results (evidence: `backend/app/routers/scan.py`)
- Authentication → JWT & Access Control: authenticates (evidence: `backend/app/routers/auth.py`)
- Authentication → Application Database: reads users (evidence: `backend/app/routers/auth.py`)
- JWT & Access Control → Application Database: loads user (evidence: `backend/app/auth.py`)
- Dashboard Stats → Application Database: queries scans (evidence: `backend/app/routers/dashboard.py`)
- Scan History → Application Database: queries scans (evidence: `backend/app/routers/history.py`)
- Administration → Application Database: queries records (evidence: `backend/app/routers/admin.py`)
- PDF Reports → PDF Generation: generates report (evidence: `backend/app/routers/reports.py`)
- PDF Reports → Application Database: loads scan data (evidence: `backend/app/routers/reports.py`)
- Web Application → Dashboard & Analytics: routes to (evidence: `frontend/src/App.tsx`)
- Web Application → History View: routes to (evidence: `frontend/src/App.tsx`)
- Web Application → Analytics View: routes to (evidence: `frontend/src/App.tsx`)
- Web Application → Admin View: routes to (evidence: `frontend/src/App.tsx`)
- Dashboard & Analytics → API Router: loads insights
- History View → API Router: loads scans
- Analytics View → API Router: loads analytics
- Admin View → API Router: requests admin
