# dwibon/qsentinel architecture

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

- Interactive diagram: https://gitdiagram.com/dwibon/qsentinel
- Repository: https://github.com/dwibon/qsentinel

## Overview

QSentinel is a simulation-based threat-detection prototype for teleportation-based quantum digital signatures. A user runs a test or verifies a signature in the React interface; the client calls the backend, which invokes signature or detection logic. The runtime models sentinel schedules, Pauli protection, teleportation, attacks and noise, then measures an axis-resolved fingerprint and combines statistical and protocol checks into a verdict. The graph also preserves the documented Bell-stabilizer capability. Source excerpts show the simulation and orchestration calls; the backend/API link is documented, while some backend internals are only identified by the source index.

Main entry points: [`src/qds.py`](https://github.com/dwibon/qsentinel/blob/main/src/qds.py) (QDS Signatures), [`src/qsentinel_pipeline.py`](https://github.com/dwibon/qsentinel/blob/main/src/qsentinel_pipeline.py) (Detection Pipeline), [`src/teleportation_pipeline.py`](https://github.com/dwibon/qsentinel/blob/main/src/teleportation_pipeline.py) (Channel Pipeline), [`backend/app.py`](https://github.com/dwibon/qsentinel/blob/main/backend/app.py) (Backend API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User Interface"]
  node_frontend["Threat Dashboard<br/>[App.jsx]"]
  node_api_client["API Client<br/>[api.js]"]
end

subgraph group_service["API Service"]
  node_backend["Backend API<br/>[app.py]"]
  node_qds["QDS Signatures<br/>[qds.py]"]
end

subgraph group_quantum["Quantum Simulation"]
  node_tele_pipeline["Channel Pipeline"]
  node_teleportation["Teleportation<br/>[teleportation.py]"]
  node_attacks["Attack Models<br/>[attacks.py]"]
  node_noise["Channel Noise<br/>[noise.py]"]
  node_states["Quantum States<br/>[states.py]"]
  node_twirl["Pauli Twirl<br/>[twirl.py]"]
  node_stabilizers["Bell Stabilizers<br/>[stabilizers.py]"]
end

subgraph group_detection["Detection and Protocol"]
  node_pipeline["Detection Pipeline"]
  node_sentinels["Sentinel Schedule<br/>[sentinels.py]"]
  node_measurement["Sentinel Measurement"]
  node_detector["Statistical Detector<br/>[detector.py]"]
  node_protocol["Protocol Checks<br/>[protocol.py]"]
end

node_user(("User"))

node_user -->|"runs tests"| node_frontend
node_frontend -->|"requests actions"| node_api_client
node_api_client -->|"calls API"| node_backend
node_backend -->|"invokes QDS"| node_qds
node_backend -.->|"runs detection"| node_pipeline
node_qds -->|"teleports states"| node_teleportation
node_qds -->|"applies attacks"| node_attacks
node_qds -->|"applies noise"| node_noise
node_qds -->|"measures sentinels"| node_measurement
node_qds -->|"derives schedule"| node_sentinels
node_qds -->|"protects states"| node_twirl
node_qds -->|"evaluates errors"| node_detector
node_qds -->|"checks session"| node_protocol
node_pipeline -->|"sends through channel"| node_tele_pipeline
node_pipeline -->|"generates schedule"| node_sentinels
node_pipeline -->|"applies Pauli layer"| node_twirl
node_pipeline -->|"measures sentinels"| node_measurement
node_pipeline -->|"evaluates fingerprint"| node_detector
node_pipeline -->|"checks protocol"| node_protocol
node_tele_pipeline -->|"teleports state"| node_teleportation
node_tele_pipeline -->|"applies attack"| node_attacks
node_tele_pipeline -->|"applies channel noise"| node_noise
node_tele_pipeline -->|"measures state"| node_states
node_sentinels -->|"creates sentinel states"| node_states
node_measurement -->|"measures states"| node_states

click node_frontend "https://github.com/dwibon/qsentinel/blob/main/QSentinel_Frontend_Animated/src/App.jsx"
click node_api_client "https://github.com/dwibon/qsentinel/blob/main/QSentinel_Frontend_Animated/src/api.js"
click node_backend "https://github.com/dwibon/qsentinel/blob/main/backend/app.py"
click node_qds "https://github.com/dwibon/qsentinel/blob/main/src/qds.py"
click node_pipeline "https://github.com/dwibon/qsentinel/blob/main/src/qsentinel_pipeline.py"
click node_tele_pipeline "https://github.com/dwibon/qsentinel/blob/main/src/teleportation_pipeline.py"
click node_teleportation "https://github.com/dwibon/qsentinel/blob/main/src/teleportation.py"
click node_attacks "https://github.com/dwibon/qsentinel/blob/main/src/attacks.py"
click node_noise "https://github.com/dwibon/qsentinel/blob/main/src/noise.py"
click node_states "https://github.com/dwibon/qsentinel/blob/main/src/states.py"
click node_twirl "https://github.com/dwibon/qsentinel/blob/main/src/twirl.py"
click node_sentinels "https://github.com/dwibon/qsentinel/blob/main/src/sentinels.py"
click node_measurement "https://github.com/dwibon/qsentinel/blob/main/src/sentinel_measurement.py"
click node_detector "https://github.com/dwibon/qsentinel/blob/main/src/detector.py"
click node_protocol "https://github.com/dwibon/qsentinel/blob/main/src/protocol.py"
click node_stabilizers "https://github.com/dwibon/qsentinel/blob/main/src/stabilizers.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_frontend,node_api_client,node_user toneBlue
class node_backend,node_qds toneAmber
class node_tele_pipeline,node_teleportation,node_attacks,node_noise,node_states,node_twirl,node_stabilizers toneMint
class node_pipeline,node_sentinels,node_measurement,node_detector,node_protocol toneRose
```

## Components

### User Interface

- [Threat Dashboard](https://github.com/dwibon/qsentinel/blob/main/QSentinel_Frontend_Animated/src/App.jsx): `QSentinel_Frontend_Animated/src/App.jsx`
- [API Client](https://github.com/dwibon/qsentinel/blob/main/QSentinel_Frontend_Animated/src/api.js): `QSentinel_Frontend_Animated/src/api.js`

### API Service

- [Backend API](https://github.com/dwibon/qsentinel/blob/main/backend/app.py): `backend/app.py`
- [QDS Signatures](https://github.com/dwibon/qsentinel/blob/main/src/qds.py): `src/qds.py`

### Quantum Simulation

- [Channel Pipeline](https://github.com/dwibon/qsentinel/blob/main/src/teleportation_pipeline.py): `src/teleportation_pipeline.py`
- [Teleportation](https://github.com/dwibon/qsentinel/blob/main/src/teleportation.py): `src/teleportation.py`
- [Attack Models](https://github.com/dwibon/qsentinel/blob/main/src/attacks.py): `src/attacks.py`
- [Channel Noise](https://github.com/dwibon/qsentinel/blob/main/src/noise.py): `src/noise.py`
- [Quantum States](https://github.com/dwibon/qsentinel/blob/main/src/states.py): `src/states.py`
- [Pauli Twirl](https://github.com/dwibon/qsentinel/blob/main/src/twirl.py): `src/twirl.py`
- [Bell Stabilizers](https://github.com/dwibon/qsentinel/blob/main/src/stabilizers.py): `src/stabilizers.py`

### Detection and Protocol

- [Detection Pipeline](https://github.com/dwibon/qsentinel/blob/main/src/qsentinel_pipeline.py): `src/qsentinel_pipeline.py`
- [Sentinel Schedule](https://github.com/dwibon/qsentinel/blob/main/src/sentinels.py): `src/sentinels.py`
- [Sentinel Measurement](https://github.com/dwibon/qsentinel/blob/main/src/sentinel_measurement.py): `src/sentinel_measurement.py`
- [Statistical Detector](https://github.com/dwibon/qsentinel/blob/main/src/detector.py): `src/detector.py`
- [Protocol Checks](https://github.com/dwibon/qsentinel/blob/main/src/protocol.py): `src/protocol.py`

### Other components

- **User**

## Connections

- User → Threat Dashboard: runs tests (evidence: `README.md`)
- Threat Dashboard → API Client: requests actions (evidence: `QSentinel_Frontend_Animated/src/App.jsx`)
- API Client → Backend API: calls API (evidence: `README.md`)
- Backend API → QDS Signatures: invokes QDS (evidence: `backend/app.py`)
- Backend API → Detection Pipeline: runs detection
- QDS Signatures → Teleportation: teleports states (evidence: `src/qds.py`)
- QDS Signatures → Attack Models: applies attacks (evidence: `src/qds.py`)
- QDS Signatures → Channel Noise: applies noise (evidence: `src/qds.py`)
- QDS Signatures → Sentinel Measurement: measures sentinels (evidence: `src/qds.py`)
- QDS Signatures → Sentinel Schedule: derives schedule (evidence: `src/qds.py`)
- QDS Signatures → Pauli Twirl: protects states (evidence: `src/qds.py`)
- QDS Signatures → Statistical Detector: evaluates errors (evidence: `src/qds.py`)
- QDS Signatures → Protocol Checks: checks session (evidence: `src/qds.py`)
- Detection Pipeline → Channel Pipeline: sends through channel (evidence: `src/qsentinel_pipeline.py`)
- Detection Pipeline → Sentinel Schedule: generates schedule (evidence: `src/qsentinel_pipeline.py`)
- Detection Pipeline → Pauli Twirl: applies Pauli layer (evidence: `src/qsentinel_pipeline.py`)
- Detection Pipeline → Sentinel Measurement: measures sentinels (evidence: `src/qsentinel_pipeline.py`)
- Detection Pipeline → Statistical Detector: evaluates fingerprint (evidence: `src/qsentinel_pipeline.py`)
- Detection Pipeline → Protocol Checks: checks protocol (evidence: `src/qsentinel_pipeline.py`)
- Channel Pipeline → Teleportation: teleports state (evidence: `src/teleportation_pipeline.py`)
- Channel Pipeline → Attack Models: applies attack (evidence: `src/teleportation_pipeline.py`)
- Channel Pipeline → Channel Noise: applies channel noise (evidence: `src/teleportation_pipeline.py`)
- Channel Pipeline → Quantum States: measures state (evidence: `src/teleportation_pipeline.py`)
- Sentinel Schedule → Quantum States: creates sentinel states (evidence: `src/sentinels.py`)
- Sentinel Measurement → Quantum States: measures states (evidence: `src/sentinel_measurement.py`)
