# ashwanth007-d/q-shield architecture

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

- Interactive diagram: https://gitdiagram.com/ashwanth007-d/q-shield
- Repository: https://github.com/ashwanth007-d/q-shield

## Overview

Q-SHIELD is an educational Streamlit simulator for demonstrating Bell-pair correlations, Eve-style interception, and CHSH measurements as intrusion indicators. A user selects a lab and run settings in the dashboard; the app runs quantum experiments, analyzes measurement counts, and presents security metrics and visualizations. Session history records experiment results. The graph preserves documented CHSH and visualization capabilities, but the excerpts do not show every UI-to-feature call, so some links are marked unverified rather than asserted as confirmed.

Main entry points: [`app.py`](https://github.com/ashwanth007-d/q-shield/blob/main/app.py) (Streamlit Dashboard), [`quantum_engine.py`](https://github.com/ashwanth007-d/q-shield/blob/main/quantum_engine.py) (Bell Experiment), [`security_engine.py`](https://github.com/ashwanth007-d/q-shield/blob/main/security_engine.py) (Security Metrics), [`visualization.py`](https://github.com/ashwanth007-d/q-shield/blob/main/visualization.py) (Outcome Chart)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Interactive Dashboard"]
  node_dashboard["Streamlit Dashboard<br/>[app.py]"]
  node_experiment_controls["Lab Controls<br/>[app.py]"]
  node_session_history["Session History<br/>[app.py]"]
end

subgraph group_quantum["Quantum Experiments"]
  node_bell_run["Bell Experiment<br/>[quantum_engine.py]"]
  node_eve_attack["Eve Attack Circuit<br/>[quantum_engine.py]"]
  node_chsh_run["CHSH Experiment<br/>[quantum_engine.py]"]
  node_simulator["Qiskit Simulator<br/>[quantum_engine.py]"]
end

subgraph group_analysis["Security Analysis"]
  node_metrics["Security Metrics<br/>[security_engine.py]"]
  node_explanation["Live Explanation<br/>[security_engine.py]"]
end

subgraph group_viz["Results Visualization"]
  node_distribution["Outcome Chart<br/>[visualization.py]"]
  node_comparison["Comparison Chart<br/>[visualization.py]"]
  node_risk_gauge["Risk Gauge<br/>[visualization.py]"]
  node_chsh_chart["CHSH Breakdown<br/>[visualization.py]"]
  node_network_flow["Channel Flow View<br/>[visualization.py]"]
end

node_user(("Dashboard User"))

node_user -->|"uses"| node_dashboard
node_dashboard -->|"presents"| node_experiment_controls
node_experiment_controls -->|"runs"| node_bell_run
node_bell_run -->|"executes on"| node_simulator
node_bell_run -->|"selects for attack"| node_eve_attack
node_experiment_controls -->|"analyzes counts"| node_metrics
node_dashboard -->|"records runs"| node_session_history
node_dashboard -->|"renders"| node_distribution
node_dashboard -.->|"runs CHSH"| node_chsh_run
node_dashboard -.->|"requests summary"| node_explanation
node_dashboard -.->|"renders comparison"| node_comparison
node_dashboard -.->|"renders risk"| node_risk_gauge
node_dashboard -.->|"renders breakdown"| node_chsh_chart
node_dashboard -.->|"renders flow"| node_network_flow
node_chsh_run -->|"executes on"| node_simulator

click node_dashboard "https://github.com/ashwanth007-d/q-shield/blob/main/app.py"
click node_experiment_controls "https://github.com/ashwanth007-d/q-shield/blob/main/app.py"
click node_session_history "https://github.com/ashwanth007-d/q-shield/blob/main/app.py"
click node_bell_run "https://github.com/ashwanth007-d/q-shield/blob/main/quantum_engine.py"
click node_eve_attack "https://github.com/ashwanth007-d/q-shield/blob/main/quantum_engine.py"
click node_chsh_run "https://github.com/ashwanth007-d/q-shield/blob/main/quantum_engine.py"
click node_simulator "https://github.com/ashwanth007-d/q-shield/blob/main/quantum_engine.py"
click node_metrics "https://github.com/ashwanth007-d/q-shield/blob/main/security_engine.py"
click node_explanation "https://github.com/ashwanth007-d/q-shield/blob/main/security_engine.py"
click node_distribution "https://github.com/ashwanth007-d/q-shield/blob/main/visualization.py"
click node_comparison "https://github.com/ashwanth007-d/q-shield/blob/main/visualization.py"
click node_risk_gauge "https://github.com/ashwanth007-d/q-shield/blob/main/visualization.py"
click node_chsh_chart "https://github.com/ashwanth007-d/q-shield/blob/main/visualization.py"
click node_network_flow "https://github.com/ashwanth007-d/q-shield/blob/main/visualization.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_dashboard,node_experiment_controls,node_session_history,node_user toneBlue
class node_bell_run,node_eve_attack,node_chsh_run,node_simulator toneAmber
class node_metrics,node_explanation toneMint
class node_distribution,node_comparison,node_risk_gauge,node_chsh_chart,node_network_flow toneRose
```

## Components

### Interactive Dashboard

- [Streamlit Dashboard](https://github.com/ashwanth007-d/q-shield/blob/main/app.py): `app.py`
- [Lab Controls](https://github.com/ashwanth007-d/q-shield/blob/main/app.py): `app.py`
- [Session History](https://github.com/ashwanth007-d/q-shield/blob/main/app.py): `app.py`

### Quantum Experiments

- [Bell Experiment](https://github.com/ashwanth007-d/q-shield/blob/main/quantum_engine.py): `quantum_engine.py`
- [Eve Attack Circuit](https://github.com/ashwanth007-d/q-shield/blob/main/quantum_engine.py): `quantum_engine.py`
- [CHSH Experiment](https://github.com/ashwanth007-d/q-shield/blob/main/quantum_engine.py): `quantum_engine.py`
- [Qiskit Simulator](https://github.com/ashwanth007-d/q-shield/blob/main/quantum_engine.py): `quantum_engine.py`

### Security Analysis

- [Security Metrics](https://github.com/ashwanth007-d/q-shield/blob/main/security_engine.py): `security_engine.py`
- [Live Explanation](https://github.com/ashwanth007-d/q-shield/blob/main/security_engine.py): `security_engine.py`

### Results Visualization

- [Outcome Chart](https://github.com/ashwanth007-d/q-shield/blob/main/visualization.py): `visualization.py`
- [Comparison Chart](https://github.com/ashwanth007-d/q-shield/blob/main/visualization.py): `visualization.py`
- [Risk Gauge](https://github.com/ashwanth007-d/q-shield/blob/main/visualization.py): `visualization.py`
- [CHSH Breakdown](https://github.com/ashwanth007-d/q-shield/blob/main/visualization.py): `visualization.py`
- [Channel Flow View](https://github.com/ashwanth007-d/q-shield/blob/main/visualization.py): `visualization.py`

### Other components

- **Dashboard User**

## Connections

- Dashboard User → Streamlit Dashboard: uses (evidence: `README.md`)
- Streamlit Dashboard → Lab Controls: presents (evidence: `app.py`)
- Lab Controls → Bell Experiment: runs (evidence: `app.py`)
- Bell Experiment → Qiskit Simulator: executes on (evidence: `quantum_engine.py`)
- Bell Experiment → Eve Attack Circuit: selects for attack (evidence: `quantum_engine.py`)
- Lab Controls → Security Metrics: analyzes counts (evidence: `app.py`)
- Streamlit Dashboard → Session History: records runs (evidence: `app.py`)
- Streamlit Dashboard → Outcome Chart: renders (evidence: `app.py`)
- Streamlit Dashboard → CHSH Experiment: runs CHSH (evidence: `app.py`)
- Streamlit Dashboard → Live Explanation: requests summary (evidence: `app.py`)
- Streamlit Dashboard → Comparison Chart: renders comparison (evidence: `app.py`)
- Streamlit Dashboard → Risk Gauge: renders risk (evidence: `app.py`)
- Streamlit Dashboard → CHSH Breakdown: renders breakdown (evidence: `app.py`)
- Streamlit Dashboard → Channel Flow View: renders flow (evidence: `app.py`)
- CHSH Experiment → Qiskit Simulator: executes on (evidence: `quantum_engine.py`)
