# spod-codes/cyberoracle architecture

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

- Interactive diagram: https://gitdiagram.com/spod-codes/cyberoracle
- Repository: https://github.com/spod-codes/cyberoracle

## Overview

CyberOracle is a network-telemetry threat-analysis application: analysts upload CSV data or monitor enrolled agents, then review risk, forecasts, explanations, and operational summaries. The main offline workflow runs from the evaluation API through the world model to a stored evaluation that the frontend presents in dashboard and briefing views. Live supervision is a separate ingestion path. Source excerpts show backend routing and model responsibilities, but frontend API wiring and several live-processing details were not sampled; those links are omitted or marked unverified.

Main entry points: [`frontend/src/App.tsx`](https://github.com/spod-codes/cyberoracle/blob/main/frontend/src/App.tsx) (Page router), [`frontend/src/lib/api.ts`](https://github.com/spod-codes/cyberoracle/blob/main/frontend/src/lib/api.ts) (API client), [`backend/routers/evaluations.py`](https://github.com/spod-codes/cyberoracle/blob/main/backend/routers/evaluations.py) (Evaluation routes), [`backend/lib/world_model.py`](https://github.com/spod-codes/cyberoracle/blob/main/backend/lib/world_model.py) (World model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Analyst interface"]
  node_app["Page router<br/>[App.tsx]"]
  node_home["Upload home<br/>[Home.tsx]"]
  node_dashboard["Risk dashboard<br/>[Dashboard.tsx]"]
  node_briefing["Incident briefing<br/>[Briefing.tsx]"]
  node_liveview["Live monitor<br/>[LiveMonitor.tsx]"]
  node_simulator["Traffic simulator<br/>[Simulator.tsx]"]
  node_api["API client<br/>[api.ts]"]
end

subgraph group_evaluation["Offline analysis"]
  node_server["API server<br/>[server.py]"]
  node_evaluation_routes["Evaluation routes<br/>[evaluations.py]"]
  node_world["World model<br/>[world_model.py]"]
  node_features["Feature extraction<br/>[features.py]"]
  node_sequence["Sequence forecasting"]
  node_explainability["Model explanations<br/>[explainability.py]"]
  node_mitre["MITRE classification"]
  node_kernel_cli["Kernel evaluation CLI<br/>[kernel_cli.py]"]
end

subgraph group_live["Live supervision"]
  node_live_routes["Live routes<br/>[live.py]"]
  node_flow_aggregation["Flow aggregation<br/>[flow_aggregator.py]"]
  node_supervision_routes["Agent supervision<br/>[supervision.py]"]
  node_agent_script["Endpoint agent<br/>[agent_script.py]"]
  node_calibration["Risk calibration<br/>[calibration.py]"]
end

subgraph group_persistence["Persistence and contracts"]
  node_evaluation_model["Evaluation records<br/>[evaluation.py]"]
  node_database[("Mongo database<br/>[db.py]")]
  node_supervision_model["Supervision records<br/>[supervision.py]"]
end

node_analyst(("Analyst"))

node_analyst -->|"uses"| node_app
node_app -->|"routes to"| node_home
node_app -->|"routes to"| node_dashboard
node_app -->|"routes to"| node_briefing
node_app -->|"routes to"| node_liveview
node_app -->|"routes to"| node_simulator
node_home -.->|"submits data"| node_api
node_dashboard -.->|"fetches results"| node_api
node_briefing -.->|"updates review"| node_api
node_liveview -.->|"reads live data"| node_api
node_simulator -.->|"sends traffic"| node_api
node_api -.->|"calls API"| node_server
node_server -->|"registers"| node_evaluation_routes
node_server -->|"registers"| node_live_routes
node_server -->|"registers"| node_supervision_routes
node_evaluation_routes -->|"runs analysis"| node_world
node_evaluation_routes -->|"reads and writes"| node_database
node_evaluation_routes -->|"returns records"| node_evaluation_model
node_world -->|"extracts features"| node_features
node_world -->|"forecasts trajectory"| node_sequence
node_world -->|"computes explanations"| node_explainability
node_world -->|"classifies tactics"| node_mitre
node_evaluation_routes -->|"launches tests"| node_kernel_cli
node_live_routes -->|"aggregates flows"| node_flow_aggregation
node_live_routes -->|"requests explanations"| node_explainability
node_live_routes -->|"uses forecasters"| node_sequence
node_supervision_routes -->|"stores agent data"| node_database
node_supervision_routes -->|"serves agent"| node_agent_script
node_supervision_routes -->|"proposes adjustments"| node_calibration
node_supervision_routes -->|"validates records"| node_supervision_model

click node_app "https://github.com/spod-codes/cyberoracle/blob/main/frontend/src/App.tsx"
click node_home "https://github.com/spod-codes/cyberoracle/blob/main/frontend/src/pages/Home.tsx"
click node_dashboard "https://github.com/spod-codes/cyberoracle/blob/main/frontend/src/pages/Dashboard.tsx"
click node_briefing "https://github.com/spod-codes/cyberoracle/blob/main/frontend/src/pages/Briefing.tsx"
click node_liveview "https://github.com/spod-codes/cyberoracle/blob/main/frontend/src/pages/LiveMonitor.tsx"
click node_simulator "https://github.com/spod-codes/cyberoracle/blob/main/frontend/src/pages/Simulator.tsx"
click node_api "https://github.com/spod-codes/cyberoracle/blob/main/frontend/src/lib/api.ts"
click node_server "https://github.com/spod-codes/cyberoracle/blob/main/backend/server.py"
click node_evaluation_routes "https://github.com/spod-codes/cyberoracle/blob/main/backend/routers/evaluations.py"
click node_world "https://github.com/spod-codes/cyberoracle/blob/main/backend/lib/world_model.py"
click node_features "https://github.com/spod-codes/cyberoracle/blob/main/backend/lib/features.py"
click node_sequence "https://github.com/spod-codes/cyberoracle/tree/main/backend/lib/sequence_models"
click node_explainability "https://github.com/spod-codes/cyberoracle/blob/main/backend/lib/explainability.py"
click node_mitre "https://github.com/spod-codes/cyberoracle/blob/main/backend/lib/mitre_classifier.py"
click node_evaluation_model "https://github.com/spod-codes/cyberoracle/blob/main/backend/models/evaluation.py"
click node_database "https://github.com/spod-codes/cyberoracle/blob/main/backend/lib/db.py"
click node_live_routes "https://github.com/spod-codes/cyberoracle/blob/main/backend/routers/live.py"
click node_flow_aggregation "https://github.com/spod-codes/cyberoracle/blob/main/backend/lib/flow_aggregator.py"
click node_supervision_routes "https://github.com/spod-codes/cyberoracle/blob/main/backend/routers/supervision.py"
click node_agent_script "https://github.com/spod-codes/cyberoracle/blob/main/backend/lib/agent_script.py"
click node_calibration "https://github.com/spod-codes/cyberoracle/blob/main/backend/lib/calibration.py"
click node_supervision_model "https://github.com/spod-codes/cyberoracle/blob/main/backend/models/supervision.py"
click node_kernel_cli "https://github.com/spod-codes/cyberoracle/blob/main/backend/kernel_cli.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_app,node_home,node_dashboard,node_briefing,node_liveview,node_simulator,node_api toneBlue
class node_server,node_evaluation_routes,node_world,node_features,node_sequence,node_explainability,node_mitre,node_kernel_cli toneAmber
class node_live_routes,node_flow_aggregation,node_supervision_routes,node_agent_script,node_calibration toneMint
class node_evaluation_model,node_database,node_supervision_model toneRose
class node_analyst toneIndigo
```

## Components

### Analyst interface

- [Page router](https://github.com/spod-codes/cyberoracle/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Upload home](https://github.com/spod-codes/cyberoracle/blob/main/frontend/src/pages/Home.tsx): `frontend/src/pages/Home.tsx`
- [Risk dashboard](https://github.com/spod-codes/cyberoracle/blob/main/frontend/src/pages/Dashboard.tsx): `frontend/src/pages/Dashboard.tsx`
- [Incident briefing](https://github.com/spod-codes/cyberoracle/blob/main/frontend/src/pages/Briefing.tsx): `frontend/src/pages/Briefing.tsx`
- [Live monitor](https://github.com/spod-codes/cyberoracle/blob/main/frontend/src/pages/LiveMonitor.tsx): `frontend/src/pages/LiveMonitor.tsx`
- [Traffic simulator](https://github.com/spod-codes/cyberoracle/blob/main/frontend/src/pages/Simulator.tsx): `frontend/src/pages/Simulator.tsx`
- [API client](https://github.com/spod-codes/cyberoracle/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`

### Offline analysis

- [API server](https://github.com/spod-codes/cyberoracle/blob/main/backend/server.py): `backend/server.py`
- [Evaluation routes](https://github.com/spod-codes/cyberoracle/blob/main/backend/routers/evaluations.py): `backend/routers/evaluations.py`
- [World model](https://github.com/spod-codes/cyberoracle/blob/main/backend/lib/world_model.py): `backend/lib/world_model.py`
- [Feature extraction](https://github.com/spod-codes/cyberoracle/blob/main/backend/lib/features.py): `backend/lib/features.py`
- [Sequence forecasting](https://github.com/spod-codes/cyberoracle/tree/main/backend/lib/sequence_models): `backend/lib/sequence_models`
- [Model explanations](https://github.com/spod-codes/cyberoracle/blob/main/backend/lib/explainability.py): `backend/lib/explainability.py`
- [MITRE classification](https://github.com/spod-codes/cyberoracle/blob/main/backend/lib/mitre_classifier.py): `backend/lib/mitre_classifier.py`
- [Kernel evaluation CLI](https://github.com/spod-codes/cyberoracle/blob/main/backend/kernel_cli.py): `backend/kernel_cli.py`

### Live supervision

- [Live routes](https://github.com/spod-codes/cyberoracle/blob/main/backend/routers/live.py): `backend/routers/live.py`
- [Flow aggregation](https://github.com/spod-codes/cyberoracle/blob/main/backend/lib/flow_aggregator.py): `backend/lib/flow_aggregator.py`
- [Agent supervision](https://github.com/spod-codes/cyberoracle/blob/main/backend/routers/supervision.py): `backend/routers/supervision.py`
- [Endpoint agent](https://github.com/spod-codes/cyberoracle/blob/main/backend/lib/agent_script.py): `backend/lib/agent_script.py`
- [Risk calibration](https://github.com/spod-codes/cyberoracle/blob/main/backend/lib/calibration.py): `backend/lib/calibration.py`

### Persistence and contracts

- [Evaluation records](https://github.com/spod-codes/cyberoracle/blob/main/backend/models/evaluation.py): `backend/models/evaluation.py`
- [Mongo database](https://github.com/spod-codes/cyberoracle/blob/main/backend/lib/db.py): `backend/lib/db.py`
- [Supervision records](https://github.com/spod-codes/cyberoracle/blob/main/backend/models/supervision.py): `backend/models/supervision.py`

### Other components

- **Analyst**

## Connections

- Analyst → Page router: uses
- Page router → Upload home: routes to (evidence: `frontend/src/App.tsx`)
- Page router → Risk dashboard: routes to (evidence: `frontend/src/App.tsx`)
- Page router → Incident briefing: routes to (evidence: `frontend/src/App.tsx`)
- Page router → Live monitor: routes to (evidence: `frontend/src/App.tsx`)
- Page router → Traffic simulator: routes to (evidence: `frontend/src/App.tsx`)
- Upload home → API client: submits data
- Risk dashboard → API client: fetches results
- Incident briefing → API client: updates review
- Live monitor → API client: reads live data
- Traffic simulator → API client: sends traffic
- API client → API server: calls API
- API server → Evaluation routes: registers (evidence: `backend/server.py`)
- API server → Live routes: registers (evidence: `backend/server.py`)
- API server → Agent supervision: registers (evidence: `backend/server.py`)
- Evaluation routes → World model: runs analysis (evidence: `backend/routers/evaluations.py`)
- Evaluation routes → Mongo database: reads and writes (evidence: `backend/routers/evaluations.py`)
- Evaluation routes → Evaluation records: returns records (evidence: `backend/routers/evaluations.py`)
- World model → Feature extraction: extracts features (evidence: `backend/lib/world_model.py`)
- World model → Sequence forecasting: forecasts trajectory (evidence: `backend/lib/world_model.py`)
- World model → Model explanations: computes explanations (evidence: `backend/lib/world_model.py`)
- World model → MITRE classification: classifies tactics (evidence: `backend/lib/world_model.py`)
- Evaluation routes → Kernel evaluation CLI: launches tests (evidence: `backend/routers/evaluations.py`)
- Live routes → Flow aggregation: aggregates flows (evidence: `backend/routers/live.py`)
- Live routes → Model explanations: requests explanations (evidence: `backend/routers/live.py`)
- Live routes → Sequence forecasting: uses forecasters (evidence: `backend/routers/live.py`)
- Agent supervision → Mongo database: stores agent data (evidence: `backend/routers/supervision.py`)
- Agent supervision → Endpoint agent: serves agent (evidence: `backend/routers/supervision.py`)
- Agent supervision → Risk calibration: proposes adjustments (evidence: `backend/routers/supervision.py`)
- Agent supervision → Supervision records: validates records (evidence: `backend/routers/supervision.py`)
