# blackbox-sentinel/blackbox_sentinel architecture

> Architecture diagram of the GitHub repository blackbox-sentinel/blackbox_sentinel, 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/blackbox-sentinel/blackbox_sentinel
- Repository: https://github.com/blackbox-sentinel/blackbox_sentinel

## Overview

BlackBox Sentinel is an inline network-defense appliance with a software simulation path. Its principal workflow captures or generates traffic, extracts window features, scores anomalies, gates containment through authenticated evidence and quorum, records decisions, and presents telemetry; physical relay isolation and tamper response are hardware-facing capabilities. The README also documents a kiosk, REST API, 3D CAD studio, and circuit simulator. The graph combines sampled source relationships, SOURCE INDEX references, and README-documented capabilities; unsampled implementation details are not inferred.

Main entry points: [`sentinel_pipeline.py`](https://github.com/blackbox-sentinel/blackbox_sentinel/blob/main/sentinel_pipeline.py) (Sentinel pipeline), [`m3-ml-ledger/src/m3_decision_path.py`](https://github.com/blackbox-sentinel/blackbox_sentinel/blob/main/m3-ml-ledger/src/m3_decision_path.py) (Decision orchestration), [`common/hal/hal_base.py`](https://github.com/blackbox-sentinel/blackbox_sentinel/blob/main/common/hal/hal_base.py) (Hardware abstraction), [`m3-ml-ledger/src/trusted_controller_sim.py`](https://github.com/blackbox-sentinel/blackbox_sentinel/blob/main/m3-ml-ledger/src/trusted_controller_sim.py) (Trusted controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_traffic["Traffic and detection"]
  node_simtraffic["Traffic generator"]
  node_features["Feature extraction"]
  node_adaptive["Adaptive inference<br/>[predict_v3.py]"]
  node_legacydetect["Legacy inference<br/>[predict.py]"]
  node_pipeline["Sentinel pipeline"]
end

subgraph group_decision["Evidence and containment"]
  node_auth["Authenticated envelopes"]
  node_evidence["Evidence contracts"]
  node_quorum["Quorum state<br/>[quorum_state.py]"]
  node_decisionpath["Decision orchestration"]
  node_controller["Trusted controller"]
  node_transport["Evidence transport"]
  node_ledger[("Forensic ledger<br/>[ledger.py]")]
end

subgraph group_hardware["Hardware and security"]
  node_relay["Relay controller"]
  node_hal["Hardware abstraction<br/>[hal_base.py]"]
  node_trusted["Security controller"]
end

subgraph group_interface["Telemetry and interface"]
  node_telemetry["Normalized telemetry<br/>[telemetry.py]"]
  node_dashboard["Touch dashboard<br/>[dashboard.py]"]
  node_desktop["Tactical GUI<br/>[app.py]"]
  node_kiosk["Web kiosk<br/>[server.py]"]
  node_api["Hardware API"]
  node_cad["3D CAD studio<br/>[cad_viewer.js]"]
  node_circuit["Circuit simulator<br/>[simulator.js]"]
end

node_operator(("Operator"))

node_operator -->|"starts defense"| node_pipeline
node_simtraffic -->|"provides packets"| node_features
node_pipeline -->|"generates traffic"| node_simtraffic
node_pipeline -->|"extracts features"| node_features
node_pipeline -->|"scores windows"| node_adaptive
node_pipeline -.->|"scores traffic"| node_legacydetect
node_pipeline -->|"requests decision"| node_decisionpath
node_pipeline -->|"uses transport"| node_transport
node_decisionpath -->|"binds evidence"| node_auth
node_decisionpath -->|"evaluates evidence"| node_evidence
node_decisionpath -->|"evaluates votes"| node_quorum
node_decisionpath -->|"requests containment"| node_controller
node_decisionpath -->|"records decision"| node_ledger
node_transport -->|"authenticates messages"| node_auth
node_transport -->|"carries votes"| node_quorum
node_controller -->|"verifies receipt"| node_evidence
node_controller -->|"checks approval"| node_quorum
node_pipeline -->|"uses hardware layer"| node_hal
node_hal -.->|"controls relay"| node_relay
node_trusted -.->|"enforces isolation"| node_relay
node_pipeline -->|"publishes status"| node_telemetry
node_dashboard -->|"reads telemetry"| node_telemetry
node_operator -->|"uses kiosk UI"| node_desktop
node_desktop -->|"accesses hardware"| node_hal
node_desktop -->|"records override"| node_ledger
node_operator -->|"opens kiosk"| node_kiosk
node_kiosk -->|"serves CAD studio"| node_cad
node_kiosk -->|"serves simulator"| node_circuit
node_operator -->|"uses hardware API"| node_api
node_api -->|"uses hardware layer"| node_hal

click node_simtraffic "https://github.com/blackbox-sentinel/blackbox_sentinel/blob/main/m2-systems/sim/traffic_generator.py"
click node_features "https://github.com/blackbox-sentinel/blackbox_sentinel/blob/main/ml/feature_pipeline_v2.py"
click node_adaptive "https://github.com/blackbox-sentinel/blackbox_sentinel/blob/main/m3-ml-ledger/src/predict_v3.py"
click node_legacydetect "https://github.com/blackbox-sentinel/blackbox_sentinel/blob/main/m3-ml-ledger/src/predict.py"
click node_pipeline "https://github.com/blackbox-sentinel/blackbox_sentinel/blob/main/sentinel_pipeline.py"
click node_auth "https://github.com/blackbox-sentinel/blackbox_sentinel/blob/main/m3-ml-ledger/src/authenticated_envelope.py"
click node_evidence "https://github.com/blackbox-sentinel/blackbox_sentinel/blob/main/m3-ml-ledger/src/m3_security_contracts.py"
click node_quorum "https://github.com/blackbox-sentinel/blackbox_sentinel/blob/main/m3-ml-ledger/src/quorum_state.py"
click node_decisionpath "https://github.com/blackbox-sentinel/blackbox_sentinel/blob/main/m3-ml-ledger/src/m3_decision_path.py"
click node_controller "https://github.com/blackbox-sentinel/blackbox_sentinel/blob/main/m3-ml-ledger/src/trusted_controller_sim.py"
click node_transport "https://github.com/blackbox-sentinel/blackbox_sentinel/blob/main/m2-systems/src/evidence_transport.py"
click node_ledger "https://github.com/blackbox-sentinel/blackbox_sentinel/blob/main/ml/ledger.py"
click node_relay "https://github.com/blackbox-sentinel/blackbox_sentinel/blob/main/m1-hardware/src/relay_controller.py"
click node_hal "https://github.com/blackbox-sentinel/blackbox_sentinel/blob/main/common/hal/hal_base.py"
click node_trusted "https://github.com/blackbox-sentinel/blackbox_sentinel/blob/main/security/trusted_controller.py"
click node_telemetry "https://github.com/blackbox-sentinel/blackbox_sentinel/blob/main/integration/telemetry.py"
click node_dashboard "https://github.com/blackbox-sentinel/blackbox_sentinel/blob/main/gui/dashboard.py"
click node_desktop "https://github.com/blackbox-sentinel/blackbox_sentinel/blob/main/m4-gui-venture/src/app.py"
click node_kiosk "https://github.com/blackbox-sentinel/blackbox_sentinel/blob/main/m4-gui-venture/server.py"
click node_api "https://github.com/blackbox-sentinel/blackbox_sentinel/blob/main/m4-gui-venture/hw_simulator_server.py"
click node_cad "https://github.com/blackbox-sentinel/blackbox_sentinel/blob/main/m4-gui-venture/web/cad_viewer.js"
click node_circuit "https://github.com/blackbox-sentinel/blackbox_sentinel/blob/main/m4-gui-venture/web/simulator.js"

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_simtraffic,node_features,node_adaptive,node_legacydetect,node_pipeline toneBlue
class node_auth,node_evidence,node_quorum,node_decisionpath,node_controller,node_transport,node_ledger toneAmber
class node_relay,node_hal,node_trusted toneMint
class node_telemetry,node_dashboard,node_desktop,node_kiosk,node_api,node_cad,node_circuit toneRose
class node_operator toneIndigo
```

## Components

### Traffic and detection

- [Traffic generator](https://github.com/blackbox-sentinel/blackbox_sentinel/blob/main/m2-systems/sim/traffic_generator.py): `m2-systems/sim/traffic_generator.py`
- [Feature extraction](https://github.com/blackbox-sentinel/blackbox_sentinel/blob/main/ml/feature_pipeline_v2.py): `ml/feature_pipeline_v2.py`
- [Adaptive inference](https://github.com/blackbox-sentinel/blackbox_sentinel/blob/main/m3-ml-ledger/src/predict_v3.py): `m3-ml-ledger/src/predict_v3.py`
- [Legacy inference](https://github.com/blackbox-sentinel/blackbox_sentinel/blob/main/m3-ml-ledger/src/predict.py): `m3-ml-ledger/src/predict.py`
- [Sentinel pipeline](https://github.com/blackbox-sentinel/blackbox_sentinel/blob/main/sentinel_pipeline.py): `sentinel_pipeline.py`

### Evidence and containment

- [Authenticated envelopes](https://github.com/blackbox-sentinel/blackbox_sentinel/blob/main/m3-ml-ledger/src/authenticated_envelope.py): `m3-ml-ledger/src/authenticated_envelope.py`
- [Evidence contracts](https://github.com/blackbox-sentinel/blackbox_sentinel/blob/main/m3-ml-ledger/src/m3_security_contracts.py): `m3-ml-ledger/src/m3_security_contracts.py`
- [Quorum state](https://github.com/blackbox-sentinel/blackbox_sentinel/blob/main/m3-ml-ledger/src/quorum_state.py): `m3-ml-ledger/src/quorum_state.py`
- [Decision orchestration](https://github.com/blackbox-sentinel/blackbox_sentinel/blob/main/m3-ml-ledger/src/m3_decision_path.py): `m3-ml-ledger/src/m3_decision_path.py`
- [Trusted controller](https://github.com/blackbox-sentinel/blackbox_sentinel/blob/main/m3-ml-ledger/src/trusted_controller_sim.py): `m3-ml-ledger/src/trusted_controller_sim.py`
- [Evidence transport](https://github.com/blackbox-sentinel/blackbox_sentinel/blob/main/m2-systems/src/evidence_transport.py): `m2-systems/src/evidence_transport.py`
- [Forensic ledger](https://github.com/blackbox-sentinel/blackbox_sentinel/blob/main/ml/ledger.py): `ml/ledger.py`

### Hardware and security

- [Relay controller](https://github.com/blackbox-sentinel/blackbox_sentinel/blob/main/m1-hardware/src/relay_controller.py): `m1-hardware/src/relay_controller.py`
- [Hardware abstraction](https://github.com/blackbox-sentinel/blackbox_sentinel/blob/main/common/hal/hal_base.py): `common/hal/hal_base.py`
- [Security controller](https://github.com/blackbox-sentinel/blackbox_sentinel/blob/main/security/trusted_controller.py): `security/trusted_controller.py`

### Telemetry and interface

- [Normalized telemetry](https://github.com/blackbox-sentinel/blackbox_sentinel/blob/main/integration/telemetry.py): `integration/telemetry.py`
- [Touch dashboard](https://github.com/blackbox-sentinel/blackbox_sentinel/blob/main/gui/dashboard.py): `gui/dashboard.py`
- [Tactical GUI](https://github.com/blackbox-sentinel/blackbox_sentinel/blob/main/m4-gui-venture/src/app.py): `m4-gui-venture/src/app.py`
- [Web kiosk](https://github.com/blackbox-sentinel/blackbox_sentinel/blob/main/m4-gui-venture/server.py): `m4-gui-venture/server.py`
- [Hardware API](https://github.com/blackbox-sentinel/blackbox_sentinel/blob/main/m4-gui-venture/hw_simulator_server.py): `m4-gui-venture/hw_simulator_server.py`
- [3D CAD studio](https://github.com/blackbox-sentinel/blackbox_sentinel/blob/main/m4-gui-venture/web/cad_viewer.js): `m4-gui-venture/web/cad_viewer.js`
- [Circuit simulator](https://github.com/blackbox-sentinel/blackbox_sentinel/blob/main/m4-gui-venture/web/simulator.js): `m4-gui-venture/web/simulator.js`

### Other components

- **Operator**

## Connections

- Operator → Sentinel pipeline: starts defense (evidence: `README.md`)
- Traffic generator → Feature extraction: provides packets (evidence: `sentinel_pipeline.py`)
- Sentinel pipeline → Traffic generator: generates traffic (evidence: `sentinel_pipeline.py`)
- Sentinel pipeline → Feature extraction: extracts features (evidence: `sentinel_pipeline.py`)
- Sentinel pipeline → Adaptive inference: scores windows (evidence: `sentinel_pipeline.py`)
- Sentinel pipeline → Legacy inference: scores traffic
- Sentinel pipeline → Decision orchestration: requests decision (evidence: `sentinel_pipeline.py`)
- Sentinel pipeline → Evidence transport: uses transport (evidence: `sentinel_pipeline.py`)
- Decision orchestration → Authenticated envelopes: binds evidence (evidence: `m3-ml-ledger/src/m3_decision_path.py`)
- Decision orchestration → Evidence contracts: evaluates evidence (evidence: `m3-ml-ledger/src/m3_decision_path.py`)
- Decision orchestration → Quorum state: evaluates votes (evidence: `m3-ml-ledger/src/m3_decision_path.py`)
- Decision orchestration → Trusted controller: requests containment (evidence: `m3-ml-ledger/src/m3_decision_path.py`)
- Decision orchestration → Forensic ledger: records decision (evidence: `m3-ml-ledger/src/m3_decision_path.py`)
- Evidence transport → Authenticated envelopes: authenticates messages (evidence: `m2-systems/src/evidence_transport.py`)
- Evidence transport → Quorum state: carries votes (evidence: `m2-systems/src/evidence_transport.py`)
- Trusted controller → Evidence contracts: verifies receipt (evidence: `m3-ml-ledger/src/trusted_controller_sim.py`)
- Trusted controller → Quorum state: checks approval (evidence: `m3-ml-ledger/src/trusted_controller_sim.py`)
- Sentinel pipeline → Hardware abstraction: uses hardware layer (evidence: `sentinel_pipeline.py`)
- Hardware abstraction → Relay controller: controls relay
- Security controller → Relay controller: enforces isolation
- Sentinel pipeline → Normalized telemetry: publishes status (evidence: `sentinel_pipeline.py`)
- Touch dashboard → Normalized telemetry: reads telemetry (evidence: `gui/dashboard.py`)
- Operator → Tactical GUI: uses kiosk UI (evidence: `README.md`)
- Tactical GUI → Hardware abstraction: accesses hardware (evidence: `m4-gui-venture/src/app.py`)
- Tactical GUI → Forensic ledger: records override (evidence: `m4-gui-venture/src/app.py`)
- Operator → Web kiosk: opens kiosk (evidence: `README.md`)
- Web kiosk → 3D CAD studio: serves CAD studio (evidence: `README.md`)
- Web kiosk → Circuit simulator: serves simulator (evidence: `README.md`)
- Operator → Hardware API: uses hardware API (evidence: `README.md`)
- Hardware API → Hardware abstraction: uses hardware layer (evidence: `m4-gui-venture/hw_simulator_server.py`)