# dharmpatel1857-cmyk/cybershield architecture

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

- Interactive diagram: https://gitdiagram.com/dharmpatel1857-cmyk/cybershield
- Repository: https://github.com/dharmpatel1857-cmyk/cybershield

## Overview

CyberShield is a local-first URL-review application: users sign in to the dashboard, submit a URL (or review a paused browser navigation), inspect explainable heuristic findings, and manage scan history and incidents. The FastAPI backend owns authentication, analysis, persistence, dashboard summaries, incident management, reports, and optional local-AI advice; deterministic rules determine recorded risk. The browser extension is an optional entry point. Edges reflect the excerpts, source-index references, and README; unsampled extension and API internals are not inferred beyond documented behavior.

Main entry points: [`backend/app/main.py`](https://github.com/dharmpatel1857-cmyk/cybershield/blob/master/backend/app/main.py) (FastAPI Application), [`backend/app/models.py`](https://github.com/dharmpatel1857-cmyk/cybershield/blob/master/backend/app/models.py) (Domain Records), [`backend/app/api/scans.py`](https://github.com/dharmpatel1857-cmyk/cybershield/blob/master/backend/app/api/scans.py) (Scan Endpoints), [`backend/app/db.py`](https://github.com/dharmpatel1857-cmyk/cybershield/blob/master/backend/app/db.py) (SQL Database)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["User Interfaces"]
  node_dashboard["Security Dashboard<br/>[App.tsx]"]
  node_frontend_api["Dashboard API Client<br/>[api.ts]"]
  node_extension["Navigation Review Extension<br/>[service_worker.js]"]
end

subgraph group_api["API Workflows"]
  node_app["FastAPI Application<br/>[main.py]"]
  node_auth["Account and Sessions<br/>[auth.py]"]
  node_scan_api["Scan Endpoints<br/>[scans.py]"]
  node_incident_api["Incident Tracking<br/>[incidents.py]"]
  node_settings_api["User Settings<br/>[settings.py]"]
  node_assistant_api["Assistant Endpoints<br/>[assistant.py]"]
end

subgraph group_analysis["URL Analysis"]
  node_detection["URL Rule Analysis<br/>[detection.py]"]
  node_assistant_service["Local AI Advice<br/>[assistant.py]"]
end

subgraph group_state["Identity and Data"]
  node_security["Session Security<br/>[security.py]"]
  node_models["Domain Records<br/>[models.py]"]
  node_database[("SQL Database<br/>[db.py]")]
  node_schemas["Request and Response Schemas<br/>[schemas.py]"]
end

subgraph group_insights["Insights and Reports"]
  node_dashboard_summary["Dashboard Summary<br/>[scans.py]"]
  node_reports["Report Exports<br/>[reports.py]"]
end

node_user(("User"))
node_ollama["Local Ollama"]

node_user -->|"reviews URLs"| node_dashboard
node_dashboard -->|"requests data"| node_frontend_api
node_frontend_api -->|"calls API"| node_app
node_user -->|"reviews navigation"| node_extension
node_extension -->|"submits navigation"| node_scan_api
node_app -->|"registers routes"| node_auth
node_app -->|"registers routes"| node_scan_api
node_app -->|"registers routes"| node_incident_api
node_app -->|"registers routes"| node_settings_api
node_app -->|"registers routes"| node_assistant_api
node_app -->|"registers routes"| node_reports
node_auth -->|"creates sessions"| node_security
node_auth -->|"persists accounts"| node_models
node_scan_api -->|"analyzes URL"| node_detection
node_scan_api -->|"requests AI advice"| node_assistant_service
node_scan_api -->|"stores scan findings"| node_models
node_scan_api -->|"authenticates requests"| node_security
node_incident_api -->|"manages incidents"| node_models
node_settings_api -->|"reads and updates settings"| node_models
node_assistant_api -->|"requests advice"| node_assistant_service
node_assistant_api -->|"loads scan context"| node_models
node_assistant_service -->|"sends local prompt"| node_ollama
node_dashboard_summary -->|"summarizes scans"| node_models
node_reports -->|"reads report records"| node_models
node_models -->|"defines persisted records"| node_database
node_auth -->|"uses database session"| node_database
node_scan_api -->|"uses database session"| node_database
node_incident_api -->|"uses database session"| node_database
node_settings_api -->|"uses database session"| node_database
node_assistant_api -->|"uses database session"| node_database
node_reports -->|"uses database session"| node_database

click node_dashboard "https://github.com/dharmpatel1857-cmyk/cybershield/blob/master/frontend/src/App.tsx"
click node_frontend_api "https://github.com/dharmpatel1857-cmyk/cybershield/blob/master/frontend/src/api.ts"
click node_extension "https://github.com/dharmpatel1857-cmyk/cybershield/blob/master/extension/service_worker.js"
click node_app "https://github.com/dharmpatel1857-cmyk/cybershield/blob/master/backend/app/main.py"
click node_auth "https://github.com/dharmpatel1857-cmyk/cybershield/blob/master/backend/app/api/auth.py"
click node_scan_api "https://github.com/dharmpatel1857-cmyk/cybershield/blob/master/backend/app/api/scans.py"
click node_incident_api "https://github.com/dharmpatel1857-cmyk/cybershield/blob/master/backend/app/api/incidents.py"
click node_settings_api "https://github.com/dharmpatel1857-cmyk/cybershield/blob/master/backend/app/api/settings.py"
click node_assistant_api "https://github.com/dharmpatel1857-cmyk/cybershield/blob/master/backend/app/api/assistant.py"
click node_detection "https://github.com/dharmpatel1857-cmyk/cybershield/blob/master/backend/app/services/detection.py"
click node_assistant_service "https://github.com/dharmpatel1857-cmyk/cybershield/blob/master/backend/app/services/assistant.py"
click node_security "https://github.com/dharmpatel1857-cmyk/cybershield/blob/master/backend/app/core/security.py"
click node_models "https://github.com/dharmpatel1857-cmyk/cybershield/blob/master/backend/app/models.py"
click node_database "https://github.com/dharmpatel1857-cmyk/cybershield/blob/master/backend/app/db.py"
click node_schemas "https://github.com/dharmpatel1857-cmyk/cybershield/blob/master/backend/app/schemas.py"
click node_dashboard_summary "https://github.com/dharmpatel1857-cmyk/cybershield/blob/master/backend/app/api/scans.py"
click node_reports "https://github.com/dharmpatel1857-cmyk/cybershield/blob/master/backend/app/api/reports.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_dashboard,node_frontend_api,node_extension,node_user toneBlue
class node_app,node_auth,node_scan_api,node_incident_api,node_settings_api,node_assistant_api toneAmber
class node_detection,node_assistant_service toneMint
class node_security,node_models,node_database,node_schemas toneRose
class node_dashboard_summary,node_reports,node_ollama toneIndigo
```

## Components

### User Interfaces

- [Security Dashboard](https://github.com/dharmpatel1857-cmyk/cybershield/blob/master/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Dashboard API Client](https://github.com/dharmpatel1857-cmyk/cybershield/blob/master/frontend/src/api.ts): `frontend/src/api.ts`
- [Navigation Review Extension](https://github.com/dharmpatel1857-cmyk/cybershield/blob/master/extension/service_worker.js): `extension/service_worker.js`

### API Workflows

- [FastAPI Application](https://github.com/dharmpatel1857-cmyk/cybershield/blob/master/backend/app/main.py): `backend/app/main.py`
- [Account and Sessions](https://github.com/dharmpatel1857-cmyk/cybershield/blob/master/backend/app/api/auth.py): `backend/app/api/auth.py`
- [Scan Endpoints](https://github.com/dharmpatel1857-cmyk/cybershield/blob/master/backend/app/api/scans.py): `backend/app/api/scans.py`
- [Incident Tracking](https://github.com/dharmpatel1857-cmyk/cybershield/blob/master/backend/app/api/incidents.py): `backend/app/api/incidents.py`
- [User Settings](https://github.com/dharmpatel1857-cmyk/cybershield/blob/master/backend/app/api/settings.py): `backend/app/api/settings.py`
- [Assistant Endpoints](https://github.com/dharmpatel1857-cmyk/cybershield/blob/master/backend/app/api/assistant.py): `backend/app/api/assistant.py`

### URL Analysis

- [URL Rule Analysis](https://github.com/dharmpatel1857-cmyk/cybershield/blob/master/backend/app/services/detection.py): `backend/app/services/detection.py`
- [Local AI Advice](https://github.com/dharmpatel1857-cmyk/cybershield/blob/master/backend/app/services/assistant.py): `backend/app/services/assistant.py`

### Identity and Data

- [Session Security](https://github.com/dharmpatel1857-cmyk/cybershield/blob/master/backend/app/core/security.py): `backend/app/core/security.py`
- [Domain Records](https://github.com/dharmpatel1857-cmyk/cybershield/blob/master/backend/app/models.py): `backend/app/models.py`
- [SQL Database](https://github.com/dharmpatel1857-cmyk/cybershield/blob/master/backend/app/db.py): `backend/app/db.py`
- [Request and Response Schemas](https://github.com/dharmpatel1857-cmyk/cybershield/blob/master/backend/app/schemas.py): `backend/app/schemas.py`

### Insights and Reports

- [Dashboard Summary](https://github.com/dharmpatel1857-cmyk/cybershield/blob/master/backend/app/api/scans.py): `backend/app/api/scans.py`
- [Report Exports](https://github.com/dharmpatel1857-cmyk/cybershield/blob/master/backend/app/api/reports.py): `backend/app/api/reports.py`

### Other components

- **User**
- **Local Ollama**

## Connections

- User → Security Dashboard: reviews URLs (evidence: `README.md`)
- Security Dashboard → Dashboard API Client: requests data (evidence: `frontend/src/App.tsx`)
- Dashboard API Client → FastAPI Application: calls API (evidence: `README.md`)
- User → Navigation Review Extension: reviews navigation (evidence: `README.md`)
- Navigation Review Extension → Scan Endpoints: submits navigation (evidence: `README.md`)
- FastAPI Application → Account and Sessions: registers routes (evidence: `backend/app/main.py`)
- FastAPI Application → Scan Endpoints: registers routes (evidence: `backend/app/main.py`)
- FastAPI Application → Incident Tracking: registers routes (evidence: `backend/app/main.py`)
- FastAPI Application → User Settings: registers routes (evidence: `backend/app/main.py`)
- FastAPI Application → Assistant Endpoints: registers routes (evidence: `backend/app/main.py`)
- FastAPI Application → Report Exports: registers routes (evidence: `backend/app/main.py`)
- Account and Sessions → Session Security: creates sessions (evidence: `backend/app/api/auth.py`)
- Account and Sessions → Domain Records: persists accounts (evidence: `backend/app/api/auth.py`)
- Scan Endpoints → URL Rule Analysis: analyzes URL (evidence: `backend/app/api/scans.py`)
- Scan Endpoints → Local AI Advice: requests AI advice (evidence: `backend/app/api/scans.py`)
- Scan Endpoints → Domain Records: stores scan findings (evidence: `backend/app/api/scans.py`)
- Scan Endpoints → Session Security: authenticates requests (evidence: `backend/app/api/scans.py`)
- Incident Tracking → Domain Records: manages incidents (evidence: `backend/app/api/incidents.py`)
- User Settings → Domain Records: reads and updates settings (evidence: `backend/app/api/settings.py`)
- Assistant Endpoints → Local AI Advice: requests advice (evidence: `backend/app/api/assistant.py`)
- Assistant Endpoints → Domain Records: loads scan context (evidence: `backend/app/api/assistant.py`)
- Local AI Advice → Local Ollama: sends local prompt (evidence: `backend/app/services/assistant.py`)
- Dashboard Summary → Domain Records: summarizes scans (evidence: `backend/app/api/scans.py`)
- Report Exports → Domain Records: reads report records (evidence: `backend/app/api/reports.py`)
- Domain Records → SQL Database: defines persisted records (evidence: `backend/app/models.py`)
- Account and Sessions → SQL Database: uses database session (evidence: `backend/app/api/auth.py`)
- Scan Endpoints → SQL Database: uses database session (evidence: `backend/app/api/scans.py`)
- Incident Tracking → SQL Database: uses database session (evidence: `backend/app/api/incidents.py`)
- User Settings → SQL Database: uses database session (evidence: `backend/app/api/settings.py`)
- Assistant Endpoints → SQL Database: uses database session (evidence: `backend/app/api/assistant.py`)
- Report Exports → SQL Database: uses database session (evidence: `backend/app/api/reports.py`)
