# ombharati/cyberguard architecture

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

- Interactive diagram: https://gitdiagram.com/ombharati/cyberguard
- Repository: https://github.com/ombharati/cyberguard

## Overview

CYBERGUARD accepts URL, email, and suspicious-content submissions through a web UI or API, then returns explainable risk assessments and scan history. The main lifecycle validates and records a scan, runs it synchronously or through a Redis-backed worker, analyzes it with deterministic detectors and local AI, computes a deterministic score, and persists findings. The graph also preserves optional threat intelligence and health checks. The README documents these capabilities; some subsystem links rely on its architecture description or the SOURCE INDEX because their implementation was not excerpted.

Main entry points: [`app/backend/services/orchestrator.py`](https://github.com/ombharati/cyberguard/blob/main/app/backend/services/orchestrator.py) (Scan Orchestrator), [`app/backend/main.py`](https://github.com/ombharati/cyberguard/blob/main/app/backend/main.py) (FastAPI Application), [`app/backend/services/scan_service.py`](https://github.com/ombharati/cyberguard/blob/main/app/backend/services/scan_service.py) (Scan Service), [`app/backend/core/database.py`](https://github.com/ombharati/cyberguard/blob/main/app/backend/core/database.py) (Database Sessions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User Entry"]
  node_frontend["Web Dashboard<br/>[script.js]"]
  node_api["FastAPI Application<br/>[main.py]"]
  node_v1api["Scan API<br/>[scans.py]"]
  node_compatapi["Compatibility API<br/>[frontend_compat.py]"]
  node_schemas["Request Schemas<br/>[scan.py]"]
end

subgraph group_lifecycle["Scan Lifecycle"]
  node_service["Scan Service<br/>[scan_service.py]"]
  node_queue["Redis Job Queue<br/>[queue.py]"]
  node_worker["Background Worker<br/>[worker.py]"]
  node_orchestrator["Scan Orchestrator<br/>[orchestrator.py]"]
end

subgraph group_analysis["Threat Analysis"]
  node_url["URL Heuristics<br/>[detector.py]"]
  node_ssrf["SSRF Validation<br/>[ssrf.py]"]
  node_emailparser["Email Parser<br/>[parser.py]"]
  node_emailheuristics["Email Heuristics<br/>[heuristics.py]"]
  node_risk["Risk Engine<br/>[risk_engine.py]"]
  node_intel["External Threat Intel<br/>[external_intel.py]"]
end

subgraph group_persistence["Storage and Config"]
  node_config["Runtime Settings<br/>[config.py]"]
  node_database["Database Sessions<br/>[database.py]"]
  node_models[("Scan Records<br/>[scan.py]")]
end

subgraph group_integrations["Model Integrations"]
  node_laya["Laya Adapter<br/>[laya_adapter.py]"]
  node_qwen["Qwen Adapter<br/>[qwen_adapter.py]"]
end

node_user(("User / Browser"))
node_ollama["Ollama Service"]
node_postgres[("PostgreSQL")]
node_redis[("Redis")]

node_user -->|"uses"| node_frontend
node_frontend -->|"sends HTTP scans"| node_api
node_api -->|"routes requests"| node_v1api
node_api -->|"routes requests"| node_compatapi
node_api -->|"serves assets"| node_frontend
node_v1api -->|"validates and responds"| node_schemas
node_v1api -->|"delegates scans"| node_service
node_compatapi -->|"validates and responds"| node_schemas
node_compatapi -->|"delegates scans"| node_service
node_service -->|"creates scan"| node_models
node_service -->|"executes synchronously"| node_orchestrator
node_service -->|"enqueues scan"| node_queue
node_worker -->|"dequeues scan"| node_queue
node_worker -->|"executes scan"| node_orchestrator
node_orchestrator -->|"analyzes URLs"| node_url
node_url -->|"validates host"| node_ssrf
node_orchestrator -->|"parses email"| node_emailparser
node_orchestrator -->|"checks email"| node_emailheuristics
node_emailheuristics -->|"uses parsed email"| node_emailparser
node_orchestrator -->|"scores URLs"| node_laya
node_orchestrator -->|"analyzes content"| node_qwen
node_orchestrator -.->|"queries intelligence"| node_intel
node_orchestrator -->|"calculates risk"| node_risk
node_orchestrator -->|"persists findings"| node_models
node_qwen -->|"requests inference"| node_ollama
node_api -->|"loads settings"| node_config
node_api -->|"checks database"| node_database
node_database -->|"configures connection"| node_config
node_models -->|"uses ORM base"| node_database
node_database -->|"connects to"| node_postgres
node_queue -->|"stores jobs"| node_redis
node_api -->|"checks availability"| node_queue

click node_frontend "https://github.com/ombharati/cyberguard/blob/main/app/frontend/script.js"
click node_api "https://github.com/ombharati/cyberguard/blob/main/app/backend/main.py"
click node_v1api "https://github.com/ombharati/cyberguard/blob/main/app/backend/api/v1/scans.py"
click node_compatapi "https://github.com/ombharati/cyberguard/blob/main/app/backend/api/frontend_compat.py"
click node_schemas "https://github.com/ombharati/cyberguard/blob/main/app/backend/schemas/scan.py"
click node_service "https://github.com/ombharati/cyberguard/blob/main/app/backend/services/scan_service.py"
click node_queue "https://github.com/ombharati/cyberguard/blob/main/app/backend/services/queue.py"
click node_worker "https://github.com/ombharati/cyberguard/blob/main/app/backend/services/worker.py"
click node_orchestrator "https://github.com/ombharati/cyberguard/blob/main/app/backend/services/orchestrator.py"
click node_url "https://github.com/ombharati/cyberguard/blob/main/detection/url/detector.py"
click node_ssrf "https://github.com/ombharati/cyberguard/blob/main/detection/url/ssrf.py"
click node_emailparser "https://github.com/ombharati/cyberguard/blob/main/detection/email/parser.py"
click node_emailheuristics "https://github.com/ombharati/cyberguard/blob/main/detection/email/heuristics.py"
click node_risk "https://github.com/ombharati/cyberguard/blob/main/app/backend/services/risk_engine.py"
click node_intel "https://github.com/ombharati/cyberguard/blob/main/app/backend/services/external_intel.py"
click node_laya "https://github.com/ombharati/cyberguard/blob/main/app/backend/services/ai/laya_adapter.py"
click node_qwen "https://github.com/ombharati/cyberguard/blob/main/app/backend/services/ai/qwen_adapter.py"
click node_config "https://github.com/ombharati/cyberguard/blob/main/app/backend/core/config.py"
click node_database "https://github.com/ombharati/cyberguard/blob/main/app/backend/core/database.py"
click node_models "https://github.com/ombharati/cyberguard/blob/main/app/backend/models/scan.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_frontend,node_api,node_v1api,node_compatapi,node_schemas,node_user toneBlue
class node_service,node_queue,node_worker,node_orchestrator,node_postgres,node_redis toneAmber
class node_url,node_ssrf,node_emailparser,node_emailheuristics,node_risk,node_intel toneMint
class node_config,node_database,node_models toneRose
class node_laya,node_qwen,node_ollama toneIndigo
```

## Components

### User Entry

- [Web Dashboard](https://github.com/ombharati/cyberguard/blob/main/app/frontend/script.js): `app/frontend/script.js`
- [FastAPI Application](https://github.com/ombharati/cyberguard/blob/main/app/backend/main.py): `app/backend/main.py`
- [Scan API](https://github.com/ombharati/cyberguard/blob/main/app/backend/api/v1/scans.py): `app/backend/api/v1/scans.py`
- [Compatibility API](https://github.com/ombharati/cyberguard/blob/main/app/backend/api/frontend_compat.py): `app/backend/api/frontend_compat.py`
- [Request Schemas](https://github.com/ombharati/cyberguard/blob/main/app/backend/schemas/scan.py): `app/backend/schemas/scan.py`

### Scan Lifecycle

- [Scan Service](https://github.com/ombharati/cyberguard/blob/main/app/backend/services/scan_service.py): `app/backend/services/scan_service.py`
- [Redis Job Queue](https://github.com/ombharati/cyberguard/blob/main/app/backend/services/queue.py): `app/backend/services/queue.py`
- [Background Worker](https://github.com/ombharati/cyberguard/blob/main/app/backend/services/worker.py): `app/backend/services/worker.py`
- [Scan Orchestrator](https://github.com/ombharati/cyberguard/blob/main/app/backend/services/orchestrator.py): `app/backend/services/orchestrator.py`

### Threat Analysis

- [URL Heuristics](https://github.com/ombharati/cyberguard/blob/main/detection/url/detector.py): `detection/url/detector.py`
- [SSRF Validation](https://github.com/ombharati/cyberguard/blob/main/detection/url/ssrf.py): `detection/url/ssrf.py`
- [Email Parser](https://github.com/ombharati/cyberguard/blob/main/detection/email/parser.py): `detection/email/parser.py`
- [Email Heuristics](https://github.com/ombharati/cyberguard/blob/main/detection/email/heuristics.py): `detection/email/heuristics.py`
- [Risk Engine](https://github.com/ombharati/cyberguard/blob/main/app/backend/services/risk_engine.py): `app/backend/services/risk_engine.py`
- [External Threat Intel](https://github.com/ombharati/cyberguard/blob/main/app/backend/services/external_intel.py): `app/backend/services/external_intel.py`

### Storage and Config

- [Runtime Settings](https://github.com/ombharati/cyberguard/blob/main/app/backend/core/config.py): `app/backend/core/config.py`
- [Database Sessions](https://github.com/ombharati/cyberguard/blob/main/app/backend/core/database.py): `app/backend/core/database.py`
- [Scan Records](https://github.com/ombharati/cyberguard/blob/main/app/backend/models/scan.py): `app/backend/models/scan.py`

### Model Integrations

- [Laya Adapter](https://github.com/ombharati/cyberguard/blob/main/app/backend/services/ai/laya_adapter.py): `app/backend/services/ai/laya_adapter.py`
- [Qwen Adapter](https://github.com/ombharati/cyberguard/blob/main/app/backend/services/ai/qwen_adapter.py): `app/backend/services/ai/qwen_adapter.py`

### Other components

- **User / Browser**
- **Ollama Service**
- **PostgreSQL**
- **Redis**

## Connections

- User / Browser → Web Dashboard: uses (evidence: `README.md`)
- Web Dashboard → FastAPI Application: sends HTTP scans (evidence: `README.md`)
- FastAPI Application → Scan API: routes requests (evidence: `app/backend/main.py`)
- FastAPI Application → Compatibility API: routes requests (evidence: `app/backend/main.py`)
- FastAPI Application → Web Dashboard: serves assets (evidence: `app/backend/main.py`)
- Scan API → Request Schemas: validates and responds (evidence: `app/backend/api/v1/scans.py`)
- Scan API → Scan Service: delegates scans (evidence: `app/backend/api/v1/scans.py`)
- Compatibility API → Request Schemas: validates and responds (evidence: `app/backend/api/frontend_compat.py`)
- Compatibility API → Scan Service: delegates scans (evidence: `app/backend/api/frontend_compat.py`)
- Scan Service → Scan Records: creates scan (evidence: `app/backend/services/scan_service.py`)
- Scan Service → Scan Orchestrator: executes synchronously (evidence: `app/backend/services/scan_service.py`)
- Scan Service → Redis Job Queue: enqueues scan (evidence: `app/backend/services/scan_service.py`)
- Background Worker → Redis Job Queue: dequeues scan (evidence: `app/backend/services/worker.py`)
- Background Worker → Scan Orchestrator: executes scan (evidence: `app/backend/services/worker.py`)
- Scan Orchestrator → URL Heuristics: analyzes URLs (evidence: `app/backend/services/orchestrator.py`)
- URL Heuristics → SSRF Validation: validates host (evidence: `detection/url/detector.py`)
- Scan Orchestrator → Email Parser: parses email (evidence: `app/backend/services/orchestrator.py`)
- Scan Orchestrator → Email Heuristics: checks email (evidence: `app/backend/services/orchestrator.py`)
- Email Heuristics → Email Parser: uses parsed email (evidence: `detection/email/heuristics.py`)
- Scan Orchestrator → Laya Adapter: scores URLs (evidence: `app/backend/services/orchestrator.py`)
- Scan Orchestrator → Qwen Adapter: analyzes content (evidence: `app/backend/services/orchestrator.py`)
- Scan Orchestrator → External Threat Intel: queries intelligence (evidence: `app/backend/services/orchestrator.py`)
- Scan Orchestrator → Risk Engine: calculates risk (evidence: `app/backend/services/orchestrator.py`)
- Scan Orchestrator → Scan Records: persists findings (evidence: `app/backend/services/orchestrator.py`)
- Qwen Adapter → Ollama Service: requests inference (evidence: `app/backend/services/ai/qwen_adapter.py`)
- FastAPI Application → Runtime Settings: loads settings (evidence: `app/backend/main.py`)
- FastAPI Application → Database Sessions: checks database (evidence: `app/backend/main.py`)
- Database Sessions → Runtime Settings: configures connection (evidence: `app/backend/core/database.py`)
- Scan Records → Database Sessions: uses ORM base (evidence: `app/backend/models/scan.py`)
- Database Sessions → PostgreSQL: connects to (evidence: `README.md`)
- Redis Job Queue → Redis: stores jobs (evidence: `README.md`)
- FastAPI Application → Redis Job Queue: checks availability (evidence: `app/backend/main.py`)
