# maliniaids-stack/quantum-threat-detector architecture

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

- Interactive diagram: https://gitdiagram.com/maliniaids-stack/quantum-threat-detector
- Repository: https://github.com/maliniaids-stack/quantum-threat-detector

## Overview

This is an academic, quantum-simulated digital-signature threat-detection prototype, not a physical quantum system. The main workflow is a user-selected scenario in the Streamlit console, sent to the FastAPI backend, where QDSSystem creates and distributes keys, signs or simulates an attack, verifies quantum measurements, classifies the result, and records an audit event; the result returns to the console. Separate API capabilities expose history, thresholds, detection curves, and a toy Shor demonstration. The graph follows README capabilities and sampled call sites; unsampled frontend/API wiring is shown only where documented.

Main entry points: [`qds/service.py`](https://github.com/maliniaids-stack/quantum-threat-detector/blob/main/qds/service.py) (QDS Coordinator), [`backend/main.py`](https://github.com/maliniaids-stack/quantum-threat-detector/blob/main/backend/main.py) (REST API), [`qds/protocol.py`](https://github.com/maliniaids-stack/quantum-threat-detector/blob/main/qds/protocol.py) (QDS Protocol), [`quantum/measure.py`](https://github.com/maliniaids-stack/quantum-threat-detector/blob/main/quantum/measure.py) (State Measurement)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User Interfaces"]
  node_frontend["Monitoring Console<br/>[app.py]"]
  node_backend["REST API<br/>[main.py]"]
end

subgraph group_qds["Signature Protocol"]
  node_service["QDS Coordinator<br/>[service.py]"]
  node_protocol["QDS Protocol<br/>[protocol.py]"]
end

subgraph group_quantum["Quantum Simulation"]
  node_measure["State Measurement<br/>[measure.py]"]
  node_paulis["Pauli States<br/>[paulis.py]"]
  node_bell["Bell Channel Test<br/>[bell.py]"]
  node_teleport["Teleportation Demo<br/>[teleport.py]"]
  node_shor["Shor Toy Demo<br/>[shor_toy.py]"]
end

subgraph group_detection["Threat Detection"]
  node_thresholds["Decision Thresholds<br/>[thresholds.py]"]
  node_statistics["Mismatch Statistics<br/>[statistics.py]"]
  node_classifier["Threat Classifier<br/>[classifier.py]"]
  node_replay["Replay Guard<br/>[replay.py]"]
  node_audit["Audit Ledger<br/>[audit.py]"]
end

subgraph group_attacks["Attack Simulation"]
  node_attacks["Attack Scenarios<br/>[simulate.py]"]
end

node_user(("Operator"))
node_database[("SQLite Event Store")]

node_user -->|"selects scenario"| node_frontend
node_frontend -->|"requests API"| node_backend
node_backend -->|"runs scenario"| node_service
node_backend -->|"reads history"| node_audit
node_backend -->|"computes thresholds"| node_thresholds
node_backend -->|"runs demo"| node_shor
node_service -->|"generates and verifies"| node_protocol
node_service -->|"creates forged signatures"| node_attacks
node_service -->|"checks freshness"| node_replay
node_service -->|"analyses mismatches"| node_statistics
node_service -->|"decides verdict"| node_thresholds
node_service -->|"classifies context"| node_classifier
node_service -->|"appends result"| node_audit
node_protocol -->|"prepares and measures"| node_measure
node_protocol -->|"tests channel"| node_bell
node_protocol -->|"gets QBER limit"| node_thresholds
node_measure -->|"uses eigenstates"| node_paulis
node_bell -->|"simulates measurements"| node_measure
node_bell -->|"uses eigenstates"| node_paulis
node_attacks -->|"generates attacker key"| node_protocol
node_attacks -->|"measures key copy"| node_measure
node_audit -->|"reads and writes events"| node_database
node_service -->|"returns result"| node_frontend
node_teleport -.->|"demonstrates measurement model"| node_measure

click node_frontend "https://github.com/maliniaids-stack/quantum-threat-detector/blob/main/frontend/app.py"
click node_backend "https://github.com/maliniaids-stack/quantum-threat-detector/blob/main/backend/main.py"
click node_service "https://github.com/maliniaids-stack/quantum-threat-detector/blob/main/qds/service.py"
click node_protocol "https://github.com/maliniaids-stack/quantum-threat-detector/blob/main/qds/protocol.py"
click node_measure "https://github.com/maliniaids-stack/quantum-threat-detector/blob/main/quantum/measure.py"
click node_paulis "https://github.com/maliniaids-stack/quantum-threat-detector/blob/main/quantum/paulis.py"
click node_bell "https://github.com/maliniaids-stack/quantum-threat-detector/blob/main/quantum/bell.py"
click node_teleport "https://github.com/maliniaids-stack/quantum-threat-detector/blob/main/quantum/teleport.py"
click node_shor "https://github.com/maliniaids-stack/quantum-threat-detector/blob/main/quantum/shor_toy.py"
click node_attacks "https://github.com/maliniaids-stack/quantum-threat-detector/blob/main/attacks/simulate.py"
click node_thresholds "https://github.com/maliniaids-stack/quantum-threat-detector/blob/main/detection/thresholds.py"
click node_statistics "https://github.com/maliniaids-stack/quantum-threat-detector/blob/main/detection/statistics.py"
click node_classifier "https://github.com/maliniaids-stack/quantum-threat-detector/blob/main/detection/classifier.py"
click node_replay "https://github.com/maliniaids-stack/quantum-threat-detector/blob/main/detection/replay.py"
click node_audit "https://github.com/maliniaids-stack/quantum-threat-detector/blob/main/detection/audit.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_backend toneBlue
class node_service,node_protocol,node_database toneAmber
class node_measure,node_paulis,node_bell,node_teleport,node_shor toneMint
class node_thresholds,node_statistics,node_classifier,node_replay,node_audit toneRose
class node_attacks,node_user toneIndigo
```

## Components

### User Interfaces

- [Monitoring Console](https://github.com/maliniaids-stack/quantum-threat-detector/blob/main/frontend/app.py): `frontend/app.py`
- [REST API](https://github.com/maliniaids-stack/quantum-threat-detector/blob/main/backend/main.py): `backend/main.py`

### Signature Protocol

- [QDS Coordinator](https://github.com/maliniaids-stack/quantum-threat-detector/blob/main/qds/service.py): `qds/service.py`
- [QDS Protocol](https://github.com/maliniaids-stack/quantum-threat-detector/blob/main/qds/protocol.py): `qds/protocol.py`

### Quantum Simulation

- [State Measurement](https://github.com/maliniaids-stack/quantum-threat-detector/blob/main/quantum/measure.py): `quantum/measure.py`
- [Pauli States](https://github.com/maliniaids-stack/quantum-threat-detector/blob/main/quantum/paulis.py): `quantum/paulis.py`
- [Bell Channel Test](https://github.com/maliniaids-stack/quantum-threat-detector/blob/main/quantum/bell.py): `quantum/bell.py`
- [Teleportation Demo](https://github.com/maliniaids-stack/quantum-threat-detector/blob/main/quantum/teleport.py): `quantum/teleport.py`
- [Shor Toy Demo](https://github.com/maliniaids-stack/quantum-threat-detector/blob/main/quantum/shor_toy.py): `quantum/shor_toy.py`

### Threat Detection

- [Decision Thresholds](https://github.com/maliniaids-stack/quantum-threat-detector/blob/main/detection/thresholds.py): `detection/thresholds.py`
- [Mismatch Statistics](https://github.com/maliniaids-stack/quantum-threat-detector/blob/main/detection/statistics.py): `detection/statistics.py`
- [Threat Classifier](https://github.com/maliniaids-stack/quantum-threat-detector/blob/main/detection/classifier.py): `detection/classifier.py`
- [Replay Guard](https://github.com/maliniaids-stack/quantum-threat-detector/blob/main/detection/replay.py): `detection/replay.py`
- [Audit Ledger](https://github.com/maliniaids-stack/quantum-threat-detector/blob/main/detection/audit.py): `detection/audit.py`

### Attack Simulation

- [Attack Scenarios](https://github.com/maliniaids-stack/quantum-threat-detector/blob/main/attacks/simulate.py): `attacks/simulate.py`

### Other components

- **Operator**
- **SQLite Event Store**

## Connections

- Operator → Monitoring Console: selects scenario
- Monitoring Console → REST API: requests API
- REST API → QDS Coordinator: runs scenario
- REST API → Audit Ledger: reads history
- REST API → Decision Thresholds: computes thresholds
- REST API → Shor Toy Demo: runs demo
- QDS Coordinator → QDS Protocol: generates and verifies
- QDS Coordinator → Attack Scenarios: creates forged signatures
- QDS Coordinator → Replay Guard: checks freshness
- QDS Coordinator → Mismatch Statistics: analyses mismatches
- QDS Coordinator → Decision Thresholds: decides verdict
- QDS Coordinator → Threat Classifier: classifies context
- QDS Coordinator → Audit Ledger: appends result
- QDS Protocol → State Measurement: prepares and measures
- QDS Protocol → Bell Channel Test: tests channel
- QDS Protocol → Decision Thresholds: gets QBER limit
- State Measurement → Pauli States: uses eigenstates
- Bell Channel Test → State Measurement: simulates measurements
- Bell Channel Test → Pauli States: uses eigenstates
- Attack Scenarios → QDS Protocol: generates attacker key
- Attack Scenarios → State Measurement: measures key copy
- Audit Ledger → SQLite Event Store: reads and writes events
- QDS Coordinator → Monitoring Console: returns result
- Teleportation Demo → State Measurement: demonstrates measurement model