# ohmic-guy/cyberguard architecture

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

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

## Overview

CyberGuard is an AI-assisted cyber-threat detection and response backend. Its intended workflow accepts threat inputs, routes them by modality, runs specialized detection, scores and explains results, and exposes threat and dashboard views. The excerpts verify the event envelope, modality routing, phishing-agent detector dispatch, and Redis Streams publishing; most API, ingestion, detection, scoring, and response implementations were not sampled, so their links are shown only as unverified. The tree also names API-abuse detection, although the sampled orchestrator does not route that modality.

Main entry points: [`backend/scoring`](https://github.com/ohmic-guy/cyberguard/tree/main/backend/scoring) (Threat scoring), [`backend/core/orchestrator.py`](https://github.com/ohmic-guy/cyberguard/blob/main/backend/core/orchestrator.py) (Modality router), [`backend/api/routes`](https://github.com/ohmic-guy/cyberguard/tree/main/backend/api/routes) (FastAPI routes), [`backend/core/events/event_bus.py`](https://github.com/ohmic-guy/cyberguard/blob/main/backend/core/events/event_bus.py) (Event bus)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["API and ingestion"]
  node_api["FastAPI routes"]
  node_upload["File upload"]
  node_ingeststream["Stream ingestion"]
end

subgraph group_dispatch["Event orchestration"]
  node_threatevent["Threat event<br/>[event_types.py]"]
  node_orchestrator["Modality router<br/>[orchestrator.py]"]
  node_container["Agent assembly<br/>[container.py]"]
  node_streams["Stream names<br/>[streams.py]"]
  node_eventbus["Event bus<br/>[event_bus.py]"]
end

subgraph group_detect["Threat detection"]
  node_phishing["Phishing agent<br/>[agent.py]"]
  node_phishdetectors["Phishing detectors"]
  node_deepfake["Deepfake detection"]
  node_logs["Log analysis"]
  node_apiabuse["API abuse detection"]
end

subgraph group_assess["Scoring and response"]
  node_scoring["Threat scoring"]
  node_response["Response agent<br/>[response_agent.py]"]
  node_llmproviders["LLM providers"]
end

subgraph group_state["Persistence and delivery"]
  node_mongodb[("MongoDB<br/>[mongodb.py]")]
  node_threatrepo["Threat repository"]
  node_sessionrepo["Session repository"]
  node_redis["Redis Streams"]
  node_dashboard["Dashboard and streams<br/>[dashboard.py]"]
end

node_user(("Analyst / client"))

node_user -.->|"submits input"| node_api
node_api -.->|"accepts uploads"| node_upload
node_upload -.->|"forwards events"| node_ingeststream
node_ingeststream -.->|"publishes input"| node_eventbus
node_orchestrator -->|"publishes routed events"| node_eventbus
node_orchestrator -->|"routes by modality"| node_streams
node_container -->|"constructs"| node_orchestrator
node_container -->|"constructs"| node_phishing
node_phishing -->|"dispatches detection"| node_phishdetectors
node_phishdetectors -.->|"returns findings"| node_threatevent
node_eventbus -->|"reads and writes"| node_redis
node_eventbus -->|"serializes events"| node_threatevent
node_orchestrator -.->|"routes media events"| node_deepfake
node_orchestrator -.->|"routes log events"| node_logs
node_api -.->|"submits abuse signals"| node_apiabuse
node_phishing -.->|"sends findings"| node_scoring
node_deepfake -.->|"sends findings"| node_scoring
node_logs -.->|"sends findings"| node_scoring
node_apiabuse -.->|"sends findings"| node_scoring
node_scoring -.->|"provides risk context"| node_response
node_response -.->|"requests recommendations"| node_llmproviders
node_scoring -.->|"persists results"| node_threatrepo
node_threatrepo -.->|"stores threats"| node_mongodb
node_api -.->|"uses sessions"| node_sessionrepo
node_sessionrepo -.->|"stores sessions"| node_mongodb
node_dashboard -.->|"queries threats"| node_threatrepo
node_dashboard -.->|"serves threat views"| node_user

click node_api "https://github.com/ohmic-guy/cyberguard/tree/main/backend/api/routes"
click node_upload "https://github.com/ohmic-guy/cyberguard/blob/main/backend/ingestion/file_upload_handler.py"
click node_ingeststream "https://github.com/ohmic-guy/cyberguard/blob/main/backend/ingestion/redis_stream_handler.py"
click node_threatevent "https://github.com/ohmic-guy/cyberguard/blob/main/backend/core/events/event_types.py"
click node_orchestrator "https://github.com/ohmic-guy/cyberguard/blob/main/backend/core/orchestrator.py"
click node_container "https://github.com/ohmic-guy/cyberguard/blob/main/backend/core/container.py"
click node_streams "https://github.com/ohmic-guy/cyberguard/blob/main/backend/core/events/streams.py"
click node_eventbus "https://github.com/ohmic-guy/cyberguard/blob/main/backend/core/events/event_bus.py"
click node_phishing "https://github.com/ohmic-guy/cyberguard/blob/main/backend/agents/phishing/agent.py"
click node_phishdetectors "https://github.com/ohmic-guy/cyberguard/tree/main/backend/agents/phishing/detectors"
click node_deepfake "https://github.com/ohmic-guy/cyberguard/tree/main/backend/agents/deepfake"
click node_logs "https://github.com/ohmic-guy/cyberguard/tree/main/backend/agents/log_analysis"
click node_apiabuse "https://github.com/ohmic-guy/cyberguard/tree/main/backend/agents/api_abuse"
click node_scoring "https://github.com/ohmic-guy/cyberguard/tree/main/backend/scoring"
click node_response "https://github.com/ohmic-guy/cyberguard/blob/main/backend/response/response_agent.py"
click node_llmproviders "https://github.com/ohmic-guy/cyberguard/tree/main/backend/response/providers"
click node_mongodb "https://github.com/ohmic-guy/cyberguard/blob/main/backend/db/mongodb.py"
click node_threatrepo "https://github.com/ohmic-guy/cyberguard/blob/main/backend/db/repositories/threat_repository.py"
click node_sessionrepo "https://github.com/ohmic-guy/cyberguard/blob/main/backend/db/repositories/session_repository.py"
click node_dashboard "https://github.com/ohmic-guy/cyberguard/blob/main/backend/api/routes/dashboard.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_api,node_upload,node_ingeststream,node_user toneBlue
class node_threatevent,node_orchestrator,node_container,node_streams,node_eventbus toneAmber
class node_phishing,node_phishdetectors,node_deepfake,node_logs,node_apiabuse toneMint
class node_scoring,node_response,node_llmproviders toneRose
class node_mongodb,node_threatrepo,node_sessionrepo,node_redis,node_dashboard toneIndigo
```

## Components

### API and ingestion

- [FastAPI routes](https://github.com/ohmic-guy/cyberguard/tree/main/backend/api/routes): `backend/api/routes`
- [File upload](https://github.com/ohmic-guy/cyberguard/blob/main/backend/ingestion/file_upload_handler.py): `backend/ingestion/file_upload_handler.py`
- [Stream ingestion](https://github.com/ohmic-guy/cyberguard/blob/main/backend/ingestion/redis_stream_handler.py): `backend/ingestion/redis_stream_handler.py`

### Event orchestration

- [Threat event](https://github.com/ohmic-guy/cyberguard/blob/main/backend/core/events/event_types.py): `backend/core/events/event_types.py`
- [Modality router](https://github.com/ohmic-guy/cyberguard/blob/main/backend/core/orchestrator.py): `backend/core/orchestrator.py`
- [Agent assembly](https://github.com/ohmic-guy/cyberguard/blob/main/backend/core/container.py): `backend/core/container.py`
- [Stream names](https://github.com/ohmic-guy/cyberguard/blob/main/backend/core/events/streams.py): `backend/core/events/streams.py`
- [Event bus](https://github.com/ohmic-guy/cyberguard/blob/main/backend/core/events/event_bus.py): `backend/core/events/event_bus.py`

### Threat detection

- [Phishing agent](https://github.com/ohmic-guy/cyberguard/blob/main/backend/agents/phishing/agent.py): `backend/agents/phishing/agent.py`
- [Phishing detectors](https://github.com/ohmic-guy/cyberguard/tree/main/backend/agents/phishing/detectors): `backend/agents/phishing/detectors`
- [Deepfake detection](https://github.com/ohmic-guy/cyberguard/tree/main/backend/agents/deepfake): `backend/agents/deepfake`
- [Log analysis](https://github.com/ohmic-guy/cyberguard/tree/main/backend/agents/log_analysis): `backend/agents/log_analysis`
- [API abuse detection](https://github.com/ohmic-guy/cyberguard/tree/main/backend/agents/api_abuse): `backend/agents/api_abuse`

### Scoring and response

- [Threat scoring](https://github.com/ohmic-guy/cyberguard/tree/main/backend/scoring): `backend/scoring`
- [Response agent](https://github.com/ohmic-guy/cyberguard/blob/main/backend/response/response_agent.py): `backend/response/response_agent.py`
- [LLM providers](https://github.com/ohmic-guy/cyberguard/tree/main/backend/response/providers): `backend/response/providers`

### Persistence and delivery

- [MongoDB](https://github.com/ohmic-guy/cyberguard/blob/main/backend/db/mongodb.py): `backend/db/mongodb.py`
- [Threat repository](https://github.com/ohmic-guy/cyberguard/blob/main/backend/db/repositories/threat_repository.py): `backend/db/repositories/threat_repository.py`
- [Session repository](https://github.com/ohmic-guy/cyberguard/blob/main/backend/db/repositories/session_repository.py): `backend/db/repositories/session_repository.py`
- **Redis Streams**
- [Dashboard and streams](https://github.com/ohmic-guy/cyberguard/blob/main/backend/api/routes/dashboard.py): `backend/api/routes/dashboard.py`

### Other components

- **Analyst / client**

## Connections

- Analyst / client → FastAPI routes: submits input
- FastAPI routes → File upload: accepts uploads
- File upload → Stream ingestion: forwards events
- Stream ingestion → Event bus: publishes input
- Modality router → Event bus: publishes routed events (evidence: `backend/core/orchestrator.py`)
- Modality router → Stream names: routes by modality (evidence: `backend/core/orchestrator.py`)
- Agent assembly → Modality router: constructs (evidence: `backend/core/container.py`)
- Agent assembly → Phishing agent: constructs (evidence: `backend/core/container.py`)
- Phishing agent → Phishing detectors: dispatches detection (evidence: `backend/agents/phishing/agent.py`)
- Phishing detectors → Threat event: returns findings
- Event bus → Redis Streams: reads and writes (evidence: `backend/core/events/event_bus.py`)
- Event bus → Threat event: serializes events (evidence: `backend/core/events/event_bus.py`)
- Modality router → Deepfake detection: routes media events
- Modality router → Log analysis: routes log events
- FastAPI routes → API abuse detection: submits abuse signals
- Phishing agent → Threat scoring: sends findings
- Deepfake detection → Threat scoring: sends findings
- Log analysis → Threat scoring: sends findings
- API abuse detection → Threat scoring: sends findings
- Threat scoring → Response agent: provides risk context
- Response agent → LLM providers: requests recommendations
- Threat scoring → Threat repository: persists results
- Threat repository → MongoDB: stores threats
- FastAPI routes → Session repository: uses sessions
- Session repository → MongoDB: stores sessions
- Dashboard and streams → Threat repository: queries threats
- Dashboard and streams → Analyst / client: serves threat views
