# makwana23-harshil/cyber-sentinel architecture

> Architecture diagram of the GitHub repository makwana23-harshil/cyber-sentinel, 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/makwana23-harshil/cyber-sentinel
- Repository: https://github.com/makwana23-harshil/cyber-sentinel

## Overview

CyberSentinel Pro is a browser-based threat-detection platform: users authenticate, submit SMS, email, or URLs, receive risk verdicts and evidence, and review scan history; admins manage users and platform-wide analytics. The API detection routes dispatch to modality detectors, persist scans, and serve dashboards. README capabilities include email parsing, ML and heuristic scoring, deep link inspection, optional reputation/LLM checks, and user/admin views. Several route implementations and frontend modules are unsampled, so only documented or indexed relationships are shown where direct wiring is not excerpted.

Main entry points: [`backend/api/detection_routes.py`](https://github.com/makwana23-harshil/cyber-sentinel/blob/main/backend/api/detection_routes.py) (Detection API), [`backend/detection/link/link_inspector.py`](https://github.com/makwana23-harshil/cyber-sentinel/blob/main/backend/detection/link/link_inspector.py) (Deep link inspector), [`backend/database.py`](https://github.com/makwana23-harshil/cyber-sentinel/blob/main/backend/database.py) (MongoDB), [`backend/auth/middleware.py`](https://github.com/makwana23-harshil/cyber-sentinel/blob/main/backend/auth/middleware.py) (JWT authorization)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Browser experience"]
  node_web_ui["Scanner and dashboards<br/>[scan.js]"]
  node_web_auth["Browser auth<br/>[auth.js]"]
  node_web_admin["Admin console<br/>[admin.js]"]
  node_web_history["History view<br/>[history.js]"]
end

subgraph group_access["API and identity"]
  node_app["Flask app<br/>[app.py]"]
  node_auth_routes["Auth endpoints<br/>[routes.py]"]
  node_auth_middleware["JWT authorization<br/>[middleware.py]"]
  node_detect_api["Detection API"]
  node_user_api["User API<br/>[user_routes.py]"]
  node_admin_api["Admin API<br/>[admin_routes.py]"]
end

subgraph group_analysis["Threat analysis"]
  node_sms["SMS detector<br/>[sms_detector.py]"]
  node_email["Email detector<br/>[email_detector.py]"]
  node_email_parse["Email parser<br/>[email_parser.py]"]
  node_url["URL detector<br/>[url_detector.py]"]
  node_link["Deep link inspector<br/>[link_inspector.py]"]
  node_llm["LLM inspection<br/>[llm_inspector.py]"]
  node_rules["Heuristic risk engine<br/>[rule_engine.py]"]
  node_features["URL features<br/>[features.py]"]
end

subgraph group_state["Persistence and reporting"]
  node_db[("MongoDB<br/>[database.py]")]
  node_scan_history["Scan records<br/>[scan_history.py]"]
  node_analytics["Usage analytics<br/>[analytics.py]"]
end

subgraph group_integrations["External intelligence"]
  node_vt["VirusTotal"]
  node_gsb["Google Safe Browsing"]
  node_gemini["Gemini API"]
end

node_user(("User"))
node_admin(("Administrator"))

node_user -->|"submits scans"| node_web_ui
node_user -->|"signs in"| node_web_auth
node_admin -->|"manages platform"| node_web_admin
node_web_ui -.->|"requests scans"| node_detect_api
node_web_auth -.->|"authenticates"| node_auth_routes
node_web_admin -.->|"requests administration"| node_admin_api
node_web_history -.->|"requests history"| node_user_api
node_app -->|"registers"| node_auth_routes
node_app -->|"registers"| node_detect_api
node_app -->|"registers"| node_user_api
node_app -->|"registers"| node_admin_api
node_auth_routes -->|"reads and updates"| node_db
node_auth_routes -->|"issues tokens"| node_auth_middleware
node_auth_middleware -->|"loads user"| node_db
node_detect_api -->|"guards routes"| node_auth_middleware
node_user_api -->|"guards routes"| node_auth_middleware
node_admin_api -->|"guards routes"| node_auth_middleware
node_detect_api -->|"dispatches SMS"| node_sms
node_detect_api -->|"dispatches email"| node_email
node_detect_api -->|"dispatches URLs"| node_url
node_detect_api -->|"requests email analysis"| node_llm
node_detect_api -->|"saves scans"| node_db
node_sms -->|"inspects extracted links"| node_link
node_email -->|"inspects embedded links"| node_link
node_url -->|"deep-inspects URL"| node_link
node_url -->|"extracts features"| node_features
node_link -->|"requests AI analysis"| node_llm
node_link -->|"checks reputation"| node_vt
node_link -->|"checks safe browsing"| node_gsb
node_llm -->|"generates analysis"| node_gemini
node_user_api -->|"queries user scans"| node_db
node_admin_api -->|"manages users and scans"| node_db
node_analytics -.->|"reports activity"| node_db
node_detect_api -.->|"records scan details"| node_scan_history
node_email_parse -.->|"parses message content"| node_email
node_rules -.->|"scores suspicious signals"| node_sms
node_rules -.->|"scores suspicious signals"| node_email
node_rules -.->|"scores suspicious signals"| node_url

click node_web_ui "https://github.com/makwana23-harshil/cyber-sentinel/blob/main/frontend/js/scan.js"
click node_web_auth "https://github.com/makwana23-harshil/cyber-sentinel/blob/main/frontend/js/auth.js"
click node_web_admin "https://github.com/makwana23-harshil/cyber-sentinel/blob/main/frontend/js/admin.js"
click node_web_history "https://github.com/makwana23-harshil/cyber-sentinel/blob/main/frontend/js/history.js"
click node_app "https://github.com/makwana23-harshil/cyber-sentinel/blob/main/backend/app.py"
click node_auth_routes "https://github.com/makwana23-harshil/cyber-sentinel/blob/main/backend/auth/routes.py"
click node_auth_middleware "https://github.com/makwana23-harshil/cyber-sentinel/blob/main/backend/auth/middleware.py"
click node_detect_api "https://github.com/makwana23-harshil/cyber-sentinel/blob/main/backend/api/detection_routes.py"
click node_user_api "https://github.com/makwana23-harshil/cyber-sentinel/blob/main/backend/api/user_routes.py"
click node_admin_api "https://github.com/makwana23-harshil/cyber-sentinel/blob/main/backend/api/admin_routes.py"
click node_sms "https://github.com/makwana23-harshil/cyber-sentinel/blob/main/backend/detection/sms/sms_detector.py"
click node_email "https://github.com/makwana23-harshil/cyber-sentinel/blob/main/backend/detection/email/email_detector.py"
click node_email_parse "https://github.com/makwana23-harshil/cyber-sentinel/blob/main/backend/services/email_parser.py"
click node_url "https://github.com/makwana23-harshil/cyber-sentinel/blob/main/backend/detection/url/url_detector.py"
click node_link "https://github.com/makwana23-harshil/cyber-sentinel/blob/main/backend/detection/link/link_inspector.py"
click node_llm "https://github.com/makwana23-harshil/cyber-sentinel/blob/main/backend/detection/link/llm_inspector.py"
click node_rules "https://github.com/makwana23-harshil/cyber-sentinel/blob/main/backend/services/rule_engine.py"
click node_features "https://github.com/makwana23-harshil/cyber-sentinel/blob/main/backend/detection/url/features.py"
click node_db "https://github.com/makwana23-harshil/cyber-sentinel/blob/main/backend/database.py"
click node_scan_history "https://github.com/makwana23-harshil/cyber-sentinel/blob/main/backend/models/scan_history.py"
click node_analytics "https://github.com/makwana23-harshil/cyber-sentinel/blob/main/backend/routes/analytics.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_web_ui,node_web_auth,node_web_admin,node_web_history,node_user toneBlue
class node_app,node_auth_routes,node_auth_middleware,node_detect_api,node_user_api,node_admin_api toneAmber
class node_sms,node_email,node_email_parse,node_url,node_link,node_llm,node_rules,node_features toneMint
class node_db,node_scan_history,node_analytics toneRose
class node_vt,node_gsb,node_gemini,node_admin toneIndigo
```

## Components

### Browser experience

- [Scanner and dashboards](https://github.com/makwana23-harshil/cyber-sentinel/blob/main/frontend/js/scan.js): `frontend/js/scan.js`
- [Browser auth](https://github.com/makwana23-harshil/cyber-sentinel/blob/main/frontend/js/auth.js): `frontend/js/auth.js`
- [Admin console](https://github.com/makwana23-harshil/cyber-sentinel/blob/main/frontend/js/admin.js): `frontend/js/admin.js`
- [History view](https://github.com/makwana23-harshil/cyber-sentinel/blob/main/frontend/js/history.js): `frontend/js/history.js`

### API and identity

- [Flask app](https://github.com/makwana23-harshil/cyber-sentinel/blob/main/backend/app.py): `backend/app.py`
- [Auth endpoints](https://github.com/makwana23-harshil/cyber-sentinel/blob/main/backend/auth/routes.py): `backend/auth/routes.py`
- [JWT authorization](https://github.com/makwana23-harshil/cyber-sentinel/blob/main/backend/auth/middleware.py): `backend/auth/middleware.py`
- [Detection API](https://github.com/makwana23-harshil/cyber-sentinel/blob/main/backend/api/detection_routes.py): `backend/api/detection_routes.py`
- [User API](https://github.com/makwana23-harshil/cyber-sentinel/blob/main/backend/api/user_routes.py): `backend/api/user_routes.py`
- [Admin API](https://github.com/makwana23-harshil/cyber-sentinel/blob/main/backend/api/admin_routes.py): `backend/api/admin_routes.py`

### Threat analysis

- [SMS detector](https://github.com/makwana23-harshil/cyber-sentinel/blob/main/backend/detection/sms/sms_detector.py): `backend/detection/sms/sms_detector.py`
- [Email detector](https://github.com/makwana23-harshil/cyber-sentinel/blob/main/backend/detection/email/email_detector.py): `backend/detection/email/email_detector.py`
- [Email parser](https://github.com/makwana23-harshil/cyber-sentinel/blob/main/backend/services/email_parser.py): `backend/services/email_parser.py`
- [URL detector](https://github.com/makwana23-harshil/cyber-sentinel/blob/main/backend/detection/url/url_detector.py): `backend/detection/url/url_detector.py`
- [Deep link inspector](https://github.com/makwana23-harshil/cyber-sentinel/blob/main/backend/detection/link/link_inspector.py): `backend/detection/link/link_inspector.py`
- [LLM inspection](https://github.com/makwana23-harshil/cyber-sentinel/blob/main/backend/detection/link/llm_inspector.py): `backend/detection/link/llm_inspector.py`
- [Heuristic risk engine](https://github.com/makwana23-harshil/cyber-sentinel/blob/main/backend/services/rule_engine.py): `backend/services/rule_engine.py`
- [URL features](https://github.com/makwana23-harshil/cyber-sentinel/blob/main/backend/detection/url/features.py): `backend/detection/url/features.py`

### Persistence and reporting

- [MongoDB](https://github.com/makwana23-harshil/cyber-sentinel/blob/main/backend/database.py): `backend/database.py`
- [Scan records](https://github.com/makwana23-harshil/cyber-sentinel/blob/main/backend/models/scan_history.py): `backend/models/scan_history.py`
- [Usage analytics](https://github.com/makwana23-harshil/cyber-sentinel/blob/main/backend/routes/analytics.py): `backend/routes/analytics.py`

### External intelligence

- **VirusTotal**
- **Google Safe Browsing**
- **Gemini API**

### Other components

- **User**
- **Administrator**

## Connections

- User → Scanner and dashboards: submits scans (evidence: `README.md`)
- User → Browser auth: signs in (evidence: `README.md`)
- Administrator → Admin console: manages platform (evidence: `README.md`)
- Scanner and dashboards → Detection API: requests scans
- Browser auth → Auth endpoints: authenticates
- Admin console → Admin API: requests administration
- History view → User API: requests history
- Flask app → Auth endpoints: registers (evidence: `backend/app.py`)
- Flask app → Detection API: registers (evidence: `backend/app.py`)
- Flask app → User API: registers (evidence: `backend/app.py`)
- Flask app → Admin API: registers (evidence: `backend/app.py`)
- Auth endpoints → MongoDB: reads and updates (evidence: `backend/auth/routes.py`)
- Auth endpoints → JWT authorization: issues tokens (evidence: `backend/auth/routes.py`)
- JWT authorization → MongoDB: loads user (evidence: `backend/auth/middleware.py`)
- Detection API → JWT authorization: guards routes (evidence: `backend/api/detection_routes.py`)
- User API → JWT authorization: guards routes (evidence: `backend/api/user_routes.py`)
- Admin API → JWT authorization: guards routes (evidence: `backend/api/admin_routes.py`)
- Detection API → SMS detector: dispatches SMS (evidence: `backend/api/detection_routes.py`)
- Detection API → Email detector: dispatches email (evidence: `backend/api/detection_routes.py`)
- Detection API → URL detector: dispatches URLs (evidence: `backend/api/detection_routes.py`)
- Detection API → LLM inspection: requests email analysis (evidence: `backend/api/detection_routes.py`)
- Detection API → MongoDB: saves scans (evidence: `backend/api/detection_routes.py`)
- SMS detector → Deep link inspector: inspects extracted links (evidence: `backend/detection/sms/sms_detector.py`)
- Email detector → Deep link inspector: inspects embedded links (evidence: `backend/detection/email/email_detector.py`)
- URL detector → Deep link inspector: deep-inspects URL (evidence: `backend/detection/url/url_detector.py`)
- URL detector → URL features: extracts features (evidence: `backend/detection/url/url_detector.py`)
- Deep link inspector → LLM inspection: requests AI analysis (evidence: `backend/detection/link/link_inspector.py`)
- Deep link inspector → VirusTotal: checks reputation (evidence: `backend/detection/link/link_inspector.py`)
- Deep link inspector → Google Safe Browsing: checks safe browsing (evidence: `README.md`)
- LLM inspection → Gemini API: generates analysis (evidence: `backend/detection/link/llm_inspector.py`)
- User API → MongoDB: queries user scans (evidence: `backend/api/user_routes.py`)
- Admin API → MongoDB: manages users and scans (evidence: `backend/api/admin_routes.py`)
- Usage analytics → MongoDB: reports activity
- Detection API → Scan records: records scan details
- Email parser → Email detector: parses message content
- Heuristic risk engine → SMS detector: scores suspicious signals
- Heuristic risk engine → Email detector: scores suspicious signals
- Heuristic risk engine → URL detector: scores suspicious signals
