# peerahammad/threatflow architecture

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

- Interactive diagram: https://gitdiagram.com/peerahammad/threatflow
- Repository: https://github.com/peerahammad/threatflow

## Overview

ThreatFlow replays saved network-flow samples through a stateful hybrid detector, turning per-flow attack probabilities and temporal regime estimates into persistent incident alerts for a live dashboard. The graph focuses on the documented replay workflow and major dashboard capabilities. Training and analysis scripts are excluded as offline utilities. Source excerpts show the detector’s internal calls and API wiring; dashboard-to-backend links are supported by the frontend excerpt and README.

Main entry points: [`backend/main.py`](https://github.com/peerahammad/threatflow/blob/master/backend/main.py) (FastAPI Replay API), [`frontend/static/app.js`](https://github.com/peerahammad/threatflow/blob/master/frontend/static/app.js) (Live Dashboard), [`model/inference.py`](https://github.com/peerahammad/threatflow/blob/master/model/inference.py) (Streaming Detector), [`model/switching_ssm.py`](https://github.com/peerahammad/threatflow/blob/master/model/switching_ssm.py) (Regime Model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_replay["Replay API"]
  node_api["FastAPI Replay API<br/>[main.py]"]
end

subgraph group_detection["Streaming Detection"]
  node_detector["Streaming Detector<br/>[inference.py]"]
  node_features["Feature Stream<br/>[inference.py]"]
  node_ssm["Regime Model<br/>[switching_ssm.py]"]
  node_classifier["Random Forests<br/>[inference.py]"]
end

subgraph group_monitoring["Alert Monitoring"]
  node_dashboard["Live Dashboard<br/>[app.js]"]
  node_alerter["Windowed Alerting<br/>[alerts.py]"]
end

subgraph group_assets["Runtime Data"]
  node_replaydata["Replay Flows<br/>[replay_sample.npz]"]
  node_modelartifact["Trained Model Artifact<br/>[pard_model.joblib]"]
  node_evalsummary["Evaluation Summary<br/>[eval_summary.json]"]
end

node_analyst(("Analyst"))

node_analyst -->|"operates"| node_dashboard
node_dashboard -->|"requests status"| node_api
node_dashboard -->|"controls replay"| node_api
node_api -->|"streams batches"| node_dashboard
node_api -->|"loads flows"| node_replaydata
node_api -->|"loads model"| node_modelartifact
node_api -->|"reads metrics"| node_evalsummary
node_api -->|"processes batches"| node_detector
node_detector -->|"transforms flows"| node_features
node_features -->|"updates regimes"| node_ssm
node_features -->|"supplies features"| node_classifier
node_detector -->|"updates alert state"| node_alerter
node_api -->|"serves interface"| node_dashboard

click node_api "https://github.com/peerahammad/threatflow/blob/master/backend/main.py"
click node_dashboard "https://github.com/peerahammad/threatflow/blob/master/frontend/static/app.js"
click node_detector "https://github.com/peerahammad/threatflow/blob/master/model/inference.py"
click node_features "https://github.com/peerahammad/threatflow/blob/master/model/inference.py"
click node_ssm "https://github.com/peerahammad/threatflow/blob/master/model/switching_ssm.py"
click node_classifier "https://github.com/peerahammad/threatflow/blob/master/model/inference.py"
click node_alerter "https://github.com/peerahammad/threatflow/blob/master/model/alerts.py"
click node_replaydata "https://github.com/peerahammad/threatflow/blob/master/data/replay_sample.npz"
click node_modelartifact "https://github.com/peerahammad/threatflow/blob/master/artifacts/pard_model.joblib"
click node_evalsummary "https://github.com/peerahammad/threatflow/blob/master/artifacts/eval_summary.json"

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 toneBlue
class node_detector,node_features,node_ssm,node_classifier toneAmber
class node_dashboard,node_alerter toneMint
class node_replaydata,node_modelartifact,node_evalsummary toneRose
class node_analyst toneIndigo
```

## Components

### Replay API

- [FastAPI Replay API](https://github.com/peerahammad/threatflow/blob/master/backend/main.py): `backend/main.py`

### Streaming Detection

- [Streaming Detector](https://github.com/peerahammad/threatflow/blob/master/model/inference.py): `model/inference.py`
- [Feature Stream](https://github.com/peerahammad/threatflow/blob/master/model/inference.py): `model/inference.py`
- [Regime Model](https://github.com/peerahammad/threatflow/blob/master/model/switching_ssm.py): `model/switching_ssm.py`
- [Random Forests](https://github.com/peerahammad/threatflow/blob/master/model/inference.py): `model/inference.py`

### Alert Monitoring

- [Live Dashboard](https://github.com/peerahammad/threatflow/blob/master/frontend/static/app.js): `frontend/static/app.js`
- [Windowed Alerting](https://github.com/peerahammad/threatflow/blob/master/model/alerts.py): `model/alerts.py`

### Runtime Data

- [Replay Flows](https://github.com/peerahammad/threatflow/blob/master/data/replay_sample.npz): `data/replay_sample.npz`
- [Trained Model Artifact](https://github.com/peerahammad/threatflow/blob/master/artifacts/pard_model.joblib): `artifacts/pard_model.joblib`
- [Evaluation Summary](https://github.com/peerahammad/threatflow/blob/master/artifacts/eval_summary.json): `artifacts/eval_summary.json`

### Other components

- **Analyst**

## Connections

- Analyst → Live Dashboard: operates (evidence: `README.md`)
- Live Dashboard → FastAPI Replay API: requests status (evidence: `frontend/static/app.js`)
- Live Dashboard → FastAPI Replay API: controls replay (evidence: `frontend/static/app.js`)
- FastAPI Replay API → Live Dashboard: streams batches (evidence: `README.md`)
- FastAPI Replay API → Replay Flows: loads flows (evidence: `backend/main.py`)
- FastAPI Replay API → Trained Model Artifact: loads model (evidence: `backend/main.py`)
- FastAPI Replay API → Evaluation Summary: reads metrics (evidence: `backend/main.py`)
- FastAPI Replay API → Streaming Detector: processes batches (evidence: `backend/main.py`)
- Streaming Detector → Feature Stream: transforms flows (evidence: `model/inference.py`)
- Feature Stream → Regime Model: updates regimes (evidence: `model/inference.py`)
- Feature Stream → Random Forests: supplies features (evidence: `model/inference.py`)
- Streaming Detector → Windowed Alerting: updates alert state (evidence: `model/inference.py`)
- FastAPI Replay API → Live Dashboard: serves interface (evidence: `backend/main.py`)
