# vivek-kamannavar/cyber-threat architecture

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

- Interactive diagram: https://gitdiagram.com/vivek-kamannavar/cyber-threat
- Repository: https://github.com/vivek-kamannavar/cyber-threat

## Overview

This is a passive, unidirectional network-threat monitoring prototype: flow records are ingested and normalized, analyzed over sliding windows, turned into standardized alerts, and surfaced through a SOC dashboard. The documented detection stages include heuristic threat rules and anomaly detection; alerts can be persisted and streamed to the UI. The dashboard also provides simulation and manual inspection capabilities. The graph reflects the sampled detector, parser, storage, and UI evidence plus README-documented features; unsampled backend routing details are not expanded into speculative call chains.

Main entry points: [`dashboard/src/App.jsx`](https://github.com/vivek-kamannavar/cyber-threat/blob/main/dashboard/src/App.jsx) (Dashboard app), [`engine/threat_detector.py`](https://github.com/vivek-kamannavar/cyber-threat/blob/main/engine/threat_detector.py) (Detection orchestrator), [`backend/main.py`](https://github.com/vivek-kamannavar/cyber-threat/blob/main/backend/main.py) (FastAPI gateway), [`ingest/parser.py`](https://github.com/vivek-kamannavar/cyber-threat/blob/main/ingest/parser.py) (Parse and normalize)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Flow ingestion"]
  node_parser["Parse and normalize<br/>[parser.py]"]
  node_pcap["PCAP loading<br/>[pcap_loader.py]"]
  node_generator["Traffic simulation"]
end

subgraph group_detection["Threat analysis"]
  node_features["Feature engineering<br/>[features.py]"]
  node_window["Sliding window<br/>[window_manager.py]"]
  node_heuristics["Threat rules<br/>[heuristic_rules.py]"]
  node_isolation["Isolation Forest"]
  node_detector["Detection orchestrator<br/>[threat_detector.py]"]
end

subgraph group_backend["API and state"]
  node_api["FastAPI gateway<br/>[main.py]"]
  node_database[("SQLite records<br/>[database.py]")]
end

subgraph group_dashboard["SOC dashboard"]
  node_app["Dashboard app<br/>[App.jsx]"]
  node_manual["Manual inspection"]
  node_alerts["Alert feed<br/>[AlertFeed.jsx]"]
  node_topology["Topology graph"]
  node_throughput["Throughput chart"]
  node_simulation["Simulation controls"]
end

subgraph group_copilot["AI assistance"]
  node_groq["Incident copilot<br/>[groq_service.py]"]
end

node_network(("Mirrored traffic"))
node_flowfiles["Zeek / PCAP files"]
node_analyst(("SOC analyst"))
node_groqapi{{"Groq API"}}

node_network -->|"passive flows"| node_parser
node_flowfiles -->|"parse records"| node_parser
node_flowfiles -->|"load captures"| node_pcap
node_generator -->|"simulated flows"| node_detector
node_parser -->|"normalized flows"| node_api
node_pcap -->|"capture flows"| node_api
node_api -->|"submit flows"| node_detector
node_detector -->|"add and query"| node_window
node_detector -->|"classify flows"| node_heuristics
node_detector -->|"score anomalies"| node_isolation
node_heuristics -->|"calculate features"| node_features
node_detector -->|"persist alerts"| node_database
node_api -->|"read records"| node_database
node_analyst -->|"view telemetry"| node_app
node_app -->|"REST / WebSocket"| node_api
node_app -->|"render panel"| node_manual
node_app -->|"show alerts"| node_alerts
node_app -->|"show topology"| node_topology
node_app -->|"show metrics"| node_throughput
node_app -->|"render controls"| node_simulation
node_simulation -->|"trigger simulation"| node_api
node_analyst -->|"inspect target"| node_manual
node_groq -.->|"request analysis"| node_groqapi

click node_parser "https://github.com/vivek-kamannavar/cyber-threat/blob/main/ingest/parser.py"
click node_pcap "https://github.com/vivek-kamannavar/cyber-threat/blob/main/ingest/pcap_loader.py"
click node_generator "https://github.com/vivek-kamannavar/cyber-threat/blob/main/ingest/traffic_generator.py"
click node_features "https://github.com/vivek-kamannavar/cyber-threat/blob/main/engine/features.py"
click node_window "https://github.com/vivek-kamannavar/cyber-threat/blob/main/engine/window_manager.py"
click node_heuristics "https://github.com/vivek-kamannavar/cyber-threat/blob/main/engine/models/heuristic_rules.py"
click node_isolation "https://github.com/vivek-kamannavar/cyber-threat/blob/main/engine/models/isolation_forest.py"
click node_detector "https://github.com/vivek-kamannavar/cyber-threat/blob/main/engine/threat_detector.py"
click node_api "https://github.com/vivek-kamannavar/cyber-threat/blob/main/backend/main.py"
click node_database "https://github.com/vivek-kamannavar/cyber-threat/blob/main/backend/database.py"
click node_app "https://github.com/vivek-kamannavar/cyber-threat/blob/main/dashboard/src/App.jsx"
click node_manual "https://github.com/vivek-kamannavar/cyber-threat/blob/main/dashboard/src/components/ManualInspectionPanel.jsx"
click node_alerts "https://github.com/vivek-kamannavar/cyber-threat/blob/main/dashboard/src/components/AlertFeed.jsx"
click node_topology "https://github.com/vivek-kamannavar/cyber-threat/blob/main/dashboard/src/components/NetworkTopologyGraph.jsx"
click node_throughput "https://github.com/vivek-kamannavar/cyber-threat/blob/main/dashboard/src/components/ThroughputChart.jsx"
click node_simulation "https://github.com/vivek-kamannavar/cyber-threat/blob/main/dashboard/src/components/SimulationControl.jsx"
click node_groq "https://github.com/vivek-kamannavar/cyber-threat/blob/main/backend/services/groq_service.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_parser,node_pcap,node_generator toneBlue
class node_features,node_window,node_heuristics,node_isolation,node_detector toneAmber
class node_api,node_database,node_groqapi toneMint
class node_app,node_manual,node_alerts,node_topology,node_throughput,node_simulation toneRose
class node_groq,node_network,node_flowfiles,node_analyst toneIndigo
```

## Components

### Flow ingestion

- [Parse and normalize](https://github.com/vivek-kamannavar/cyber-threat/blob/main/ingest/parser.py): `ingest/parser.py`
- [PCAP loading](https://github.com/vivek-kamannavar/cyber-threat/blob/main/ingest/pcap_loader.py): `ingest/pcap_loader.py`
- [Traffic simulation](https://github.com/vivek-kamannavar/cyber-threat/blob/main/ingest/traffic_generator.py): `ingest/traffic_generator.py`

### Threat analysis

- [Feature engineering](https://github.com/vivek-kamannavar/cyber-threat/blob/main/engine/features.py): `engine/features.py`
- [Sliding window](https://github.com/vivek-kamannavar/cyber-threat/blob/main/engine/window_manager.py): `engine/window_manager.py`
- [Threat rules](https://github.com/vivek-kamannavar/cyber-threat/blob/main/engine/models/heuristic_rules.py): `engine/models/heuristic_rules.py`
- [Isolation Forest](https://github.com/vivek-kamannavar/cyber-threat/blob/main/engine/models/isolation_forest.py): `engine/models/isolation_forest.py`
- [Detection orchestrator](https://github.com/vivek-kamannavar/cyber-threat/blob/main/engine/threat_detector.py): `engine/threat_detector.py`

### API and state

- [FastAPI gateway](https://github.com/vivek-kamannavar/cyber-threat/blob/main/backend/main.py): `backend/main.py`
- [SQLite records](https://github.com/vivek-kamannavar/cyber-threat/blob/main/backend/database.py): `backend/database.py`

### SOC dashboard

- [Dashboard app](https://github.com/vivek-kamannavar/cyber-threat/blob/main/dashboard/src/App.jsx): `dashboard/src/App.jsx`
- [Manual inspection](https://github.com/vivek-kamannavar/cyber-threat/blob/main/dashboard/src/components/ManualInspectionPanel.jsx): `dashboard/src/components/ManualInspectionPanel.jsx`
- [Alert feed](https://github.com/vivek-kamannavar/cyber-threat/blob/main/dashboard/src/components/AlertFeed.jsx): `dashboard/src/components/AlertFeed.jsx`
- [Topology graph](https://github.com/vivek-kamannavar/cyber-threat/blob/main/dashboard/src/components/NetworkTopologyGraph.jsx): `dashboard/src/components/NetworkTopologyGraph.jsx`
- [Throughput chart](https://github.com/vivek-kamannavar/cyber-threat/blob/main/dashboard/src/components/ThroughputChart.jsx): `dashboard/src/components/ThroughputChart.jsx`
- [Simulation controls](https://github.com/vivek-kamannavar/cyber-threat/blob/main/dashboard/src/components/SimulationControl.jsx): `dashboard/src/components/SimulationControl.jsx`

### AI assistance

- [Incident copilot](https://github.com/vivek-kamannavar/cyber-threat/blob/main/backend/services/groq_service.py): `backend/services/groq_service.py`

### Other components

- **Mirrored traffic**
- **Zeek / PCAP files**
- **SOC analyst**
- **Groq API**

## Connections

- Mirrored traffic → Parse and normalize: passive flows
- Zeek / PCAP files → Parse and normalize: parse records
- Zeek / PCAP files → PCAP loading: load captures
- Traffic simulation → Detection orchestrator: simulated flows
- Parse and normalize → FastAPI gateway: normalized flows
- PCAP loading → FastAPI gateway: capture flows
- FastAPI gateway → Detection orchestrator: submit flows
- Detection orchestrator → Sliding window: add and query
- Detection orchestrator → Threat rules: classify flows
- Detection orchestrator → Isolation Forest: score anomalies
- Threat rules → Feature engineering: calculate features
- Detection orchestrator → SQLite records: persist alerts
- FastAPI gateway → SQLite records: read records
- SOC analyst → Dashboard app: view telemetry
- Dashboard app → FastAPI gateway: REST / WebSocket
- Dashboard app → Manual inspection: render panel
- Dashboard app → Alert feed: show alerts
- Dashboard app → Topology graph: show topology
- Dashboard app → Throughput chart: show metrics
- Dashboard app → Simulation controls: render controls
- Simulation controls → FastAPI gateway: trigger simulation
- SOC analyst → Manual inspection: inspect target
- Incident copilot → Groq API: request analysis