# rxmna8502/sentinel-ni architecture

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

- Interactive diagram: https://gitdiagram.com/rxmna8502/sentinel-ni
- Repository: https://github.com/rxmna8502/sentinel-ni

## Overview

Sentinel / NI is an out-of-band network-security forecasting platform. Its main operator journey enrolls a remote sensor, collects and submits aggregated telemetry, builds ten-second network states, forecasts five horizons, then presents source intelligence and mitigation recommendations in the dashboard. The graph includes the agent-to-central and browser-to-central boundaries, sensor management, and the forecasting and recommendation stages. Some API/runtime and collector wiring is unsampled, so only documented or excerpt-supported links are shown.

Main entry points: [`src/api/live_runtime.py`](https://github.com/rxmna8502/sentinel-ni/blob/main/src/api/live_runtime.py) (Sensor runtime), [`frontend/app/page.tsx`](https://github.com/rxmna8502/sentinel-ni/blob/main/frontend/app/page.tsx) (Dashboard UI), [`src/api/app.py`](https://github.com/rxmna8502/sentinel-ni/blob/main/src/api/app.py) (Central API), [`src/agent/service.py`](https://github.com/rxmna8502/sentinel-ni/blob/main/src/agent/service.py) (Agent service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_collection["Telemetry collection"]
  node_agent["Agent service<br/>[service.py]"]
  node_agentclient["Telemetry client<br/>[client.py]"]
  node_telemetry["Telemetry adapters"]
end

subgraph group_central["Central platform"]
  node_api["Central API<br/>[app.py]"]
  node_sensorruntime["Sensor runtime<br/>[live_runtime.py]"]
  node_sensormanager["Sensor management<br/>[manager.py]"]
  node_sensorregistry[("Sensor registry<br/>[registry.py]")]
end

subgraph group_analysis["Forecast and response"]
  node_statebuild["State aggregation"]
  node_statebuffer["State history<br/>[state_buffer.py]"]
  node_inference["Forecast inference<br/>[inference.py]"]
  node_explanation["Forecast explanation<br/>[explanation.py]"]
  node_sourceintel["Source intelligence<br/>[source_forecast.py]"]
  node_mitigation["Mitigation policy"]
end

subgraph group_dashboard["Dashboard"]
  node_frontend["Dashboard UI<br/>[page.tsx]"]
  node_proxy["API proxy<br/>[route.ts]"]
  node_auth[("Dashboard sessions")]
  node_sensorview["Sensor views<br/>[SensorFleet.tsx]"]
  node_forecastview["Forecast view<br/>[ForecastView.tsx]"]
  node_sourceview["Source and mitigation"]
end

node_customer["Customer application"]
node_sensor(("Remote sensor"))
node_operator(("Operator"))

node_customer -.->|"observed in parallel"| node_sensor
node_sensor -->|"observed traffic"| node_agent
node_agent -->|"collects metadata"| node_telemetry
node_agent -->|"submits batches"| node_agentclient
node_agentclient -->|"sends telemetry"| node_api
node_api -->|"dispatches telemetry"| node_sensorruntime
node_sensorruntime -->|"builds states"| node_statebuild
node_sensorruntime -->|"maintains history"| node_statebuffer
node_sensorruntime -->|"requests forecasts"| node_inference
node_inference -->|"computes contributions"| node_explanation
node_sensorruntime -->|"prioritizes sources"| node_sourceintel
node_sensorruntime -->|"requests recommendations"| node_mitigation
node_api -->|"serves sensor views"| node_sensormanager
node_sensormanager -->|"reads sensor records"| node_sensorregistry
node_sensormanager -->|"reads runtime snapshot"| node_sensorruntime
node_operator -->|"uses"| node_frontend
node_frontend -->|"checks session"| node_auth
node_frontend -->|"requests data"| node_proxy
node_proxy -->|"forwards requests"| node_api
node_api -->|"returns responses"| node_proxy
node_frontend -->|"displays fleet"| node_sensorview
node_frontend -->|"displays forecast"| node_forecastview
node_frontend -->|"displays intelligence"| node_sourceview

click node_agent "https://github.com/rxmna8502/sentinel-ni/blob/main/src/agent/service.py"
click node_agentclient "https://github.com/rxmna8502/sentinel-ni/blob/main/src/agent/client.py"
click node_telemetry "https://github.com/rxmna8502/sentinel-ni/tree/main/src/telemetry"
click node_api "https://github.com/rxmna8502/sentinel-ni/blob/main/src/api/app.py"
click node_sensorruntime "https://github.com/rxmna8502/sentinel-ni/blob/main/src/api/live_runtime.py"
click node_sensormanager "https://github.com/rxmna8502/sentinel-ni/blob/main/src/sensors/manager.py"
click node_sensorregistry "https://github.com/rxmna8502/sentinel-ni/blob/main/src/sensors/registry.py"
click node_statebuild "https://github.com/rxmna8502/sentinel-ni/blob/main/src/streaming/state_aggregator.py"
click node_statebuffer "https://github.com/rxmna8502/sentinel-ni/blob/main/src/streaming/state_buffer.py"
click node_inference "https://github.com/rxmna8502/sentinel-ni/blob/main/src/forecasting/inference.py"
click node_explanation "https://github.com/rxmna8502/sentinel-ni/blob/main/src/forecasting/explanation.py"
click node_sourceintel "https://github.com/rxmna8502/sentinel-ni/blob/main/src/streaming/source_forecast.py"
click node_mitigation "https://github.com/rxmna8502/sentinel-ni/blob/main/src/evaluation/mitigation_policy.py"
click node_frontend "https://github.com/rxmna8502/sentinel-ni/blob/main/frontend/app/page.tsx"
click node_proxy "https://github.com/rxmna8502/sentinel-ni/blob/main/frontend/app/api/%5B...path%5D/route.ts"
click node_auth "https://github.com/rxmna8502/sentinel-ni/blob/main/frontend/lib/dashboard-session.ts"
click node_sensorview "https://github.com/rxmna8502/sentinel-ni/blob/main/frontend/components/SensorFleet.tsx"
click node_forecastview "https://github.com/rxmna8502/sentinel-ni/blob/main/frontend/components/ForecastView.tsx"
click node_sourceview "https://github.com/rxmna8502/sentinel-ni/blob/main/frontend/components/SourceIntelligence.tsx"

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_agent,node_agentclient,node_telemetry toneBlue
class node_api,node_sensorruntime,node_sensormanager,node_sensorregistry toneAmber
class node_statebuild,node_statebuffer,node_inference,node_explanation,node_sourceintel,node_mitigation toneMint
class node_frontend,node_proxy,node_auth,node_sensorview,node_forecastview,node_sourceview toneRose
class node_customer,node_sensor,node_operator toneIndigo
```

## Components

### Telemetry collection

- [Agent service](https://github.com/rxmna8502/sentinel-ni/blob/main/src/agent/service.py): `src/agent/service.py`
- [Telemetry client](https://github.com/rxmna8502/sentinel-ni/blob/main/src/agent/client.py): `src/agent/client.py`
- [Telemetry adapters](https://github.com/rxmna8502/sentinel-ni/tree/main/src/telemetry): `src/telemetry`

### Central platform

- [Central API](https://github.com/rxmna8502/sentinel-ni/blob/main/src/api/app.py): `src/api/app.py`
- [Sensor runtime](https://github.com/rxmna8502/sentinel-ni/blob/main/src/api/live_runtime.py): `src/api/live_runtime.py`
- [Sensor management](https://github.com/rxmna8502/sentinel-ni/blob/main/src/sensors/manager.py): `src/sensors/manager.py`
- [Sensor registry](https://github.com/rxmna8502/sentinel-ni/blob/main/src/sensors/registry.py): `src/sensors/registry.py`

### Forecast and response

- [State aggregation](https://github.com/rxmna8502/sentinel-ni/blob/main/src/streaming/state_aggregator.py): `src/streaming/state_aggregator.py`
- [State history](https://github.com/rxmna8502/sentinel-ni/blob/main/src/streaming/state_buffer.py): `src/streaming/state_buffer.py`
- [Forecast inference](https://github.com/rxmna8502/sentinel-ni/blob/main/src/forecasting/inference.py): `src/forecasting/inference.py`
- [Forecast explanation](https://github.com/rxmna8502/sentinel-ni/blob/main/src/forecasting/explanation.py): `src/forecasting/explanation.py`
- [Source intelligence](https://github.com/rxmna8502/sentinel-ni/blob/main/src/streaming/source_forecast.py): `src/streaming/source_forecast.py`
- [Mitigation policy](https://github.com/rxmna8502/sentinel-ni/blob/main/src/evaluation/mitigation_policy.py): `src/evaluation/mitigation_policy.py`

### Dashboard

- [Dashboard UI](https://github.com/rxmna8502/sentinel-ni/blob/main/frontend/app/page.tsx): `frontend/app/page.tsx`
- [API proxy](https://github.com/rxmna8502/sentinel-ni/blob/main/frontend/app/api/%5B...path%5D/route.ts): `frontend/app/api/[...path]/route.ts`
- [Dashboard sessions](https://github.com/rxmna8502/sentinel-ni/blob/main/frontend/lib/dashboard-session.ts): `frontend/lib/dashboard-session.ts`
- [Sensor views](https://github.com/rxmna8502/sentinel-ni/blob/main/frontend/components/SensorFleet.tsx): `frontend/components/SensorFleet.tsx`
- [Forecast view](https://github.com/rxmna8502/sentinel-ni/blob/main/frontend/components/ForecastView.tsx): `frontend/components/ForecastView.tsx`
- [Source and mitigation](https://github.com/rxmna8502/sentinel-ni/blob/main/frontend/components/SourceIntelligence.tsx): `frontend/components/SourceIntelligence.tsx`

### Other components

- **Customer application**
- **Remote sensor**
- **Operator**

## Connections

- Customer application → Remote sensor: observed in parallel
- Remote sensor → Agent service: observed traffic
- Agent service → Telemetry adapters: collects metadata
- Agent service → Telemetry client: submits batches
- Telemetry client → Central API: sends telemetry
- Central API → Sensor runtime: dispatches telemetry
- Sensor runtime → State aggregation: builds states
- Sensor runtime → State history: maintains history
- Sensor runtime → Forecast inference: requests forecasts
- Forecast inference → Forecast explanation: computes contributions
- Sensor runtime → Source intelligence: prioritizes sources
- Sensor runtime → Mitigation policy: requests recommendations
- Central API → Sensor management: serves sensor views
- Sensor management → Sensor registry: reads sensor records
- Sensor management → Sensor runtime: reads runtime snapshot
- Operator → Dashboard UI: uses
- Dashboard UI → Dashboard sessions: checks session
- Dashboard UI → API proxy: requests data
- API proxy → Central API: forwards requests
- Central API → API proxy: returns responses
- Dashboard UI → Sensor views: displays fleet
- Dashboard UI → Forecast view: displays forecast
- Dashboard UI → Source and mitigation: displays intelligence