# vansh28v/q-shield architecture

> Architecture diagram of the GitHub repository vansh28v/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/vansh28v/q-shield
- Repository: https://github.com/vansh28v/q-shield

## Overview

Q-SHIELD is a Next.js quantum-signature and security prototype. Its main evidenced workflow accepts an experiment request, runs quantum and signature checks with replay/threat analysis, creates telemetry, persists records, and returns the result. A separate attack endpoint simulates attacks and saves runs; authentication and event retrieval are additional API capabilities. The UI routes are present in the tree, but their runtime connections were not shown. Relationships below are limited to sampled calls and SOURCE INDEX references.

Main entry points: [`lib/security/persistence.ts`](https://github.com/vansh28v/q-shield/blob/main/lib/security/persistence.ts) (Persistence services), [`lib/security/experiment.ts`](https://github.com/vansh28v/q-shield/blob/main/lib/security/experiment.ts) (QDS experiment), [`lib/quantum/simulator.ts`](https://github.com/vansh28v/q-shield/blob/main/lib/quantum/simulator.ts) (Quantum engine), [`app/api/security/experiment/route.ts`](https://github.com/vansh28v/q-shield/blob/main/app/api/security/experiment/route.ts) (Experiment API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API workflows"]
  node_experiment_api["Experiment API<br/>[route.ts]"]
  node_attack_api["Attack API<br/>[route.ts]"]
  node_quantum_api["Quantum API<br/>[route.ts]"]
  node_auth_api["Authentication API"]
  node_events_api["Events API<br/>[route.ts]"]
end

subgraph group_quantum["Quantum simulation"]
  node_attack_simulation["Attack simulation<br/>[attacks.ts]"]
  node_quantum_engine["Quantum engine<br/>[simulator.ts]"]
  node_quantum_primitives["Quantum primitives<br/>[state.ts]"]
  node_quantum_measurement["Measurement and statistics<br/>[measurement.ts]"]
end

subgraph group_security["Security analysis"]
  node_qds_experiment["QDS experiment<br/>[experiment.ts]"]
  node_signature_verification["Signature verification<br/>[signature.ts]"]
  node_threat_detection["Threat detection<br/>[detector.ts]"]
  node_replay_ledger["Replay ledger<br/>[ledger.ts]"]
  node_telemetry["Experiment telemetry<br/>[telemetry.ts]"]
  node_session["Session handling<br/>[session.ts]"]
end

subgraph group_storage["Persistence"]
  node_persistence["Persistence services<br/>[persistence.ts]"]
  node_database[("SQLite database<br/>[db.ts]")]
end

node_experiment_api -->|"runs experiment"| node_qds_experiment
node_experiment_api -->|"supplies ledger"| node_replay_ledger
node_experiment_api -->|"creates telemetry"| node_telemetry
node_experiment_api -->|"saves results"| node_persistence
node_attack_api -->|"simulates attack"| node_attack_simulation
node_attack_api -->|"saves run"| node_persistence
node_quantum_api -->|"runs simulation"| node_quantum_engine
node_auth_api -->|"manages accounts"| node_persistence
node_auth_api -->|"sets session"| node_session
node_events_api -->|"reads events"| node_persistence
node_qds_experiment -->|"runs QDS"| node_quantum_engine
node_qds_experiment -->|"creates and verifies"| node_signature_verification
node_qds_experiment -->|"detects threats"| node_threat_detection
node_qds_experiment -->|"checks replay"| node_replay_ledger
node_attack_simulation -->|"runs experiment"| node_quantum_engine
node_attack_simulation -->|"checks replay"| node_replay_ledger
node_quantum_engine -->|"uses state operations"| node_quantum_primitives
node_quantum_engine -->|"measures and analyzes"| node_quantum_measurement
node_signature_verification -->|"uses state operations"| node_quantum_primitives
node_persistence -->|"reads and writes"| node_database
node_replay_ledger -->|"stores replay records"| node_database
node_session -->|"resolves user"| node_persistence

click node_experiment_api "https://github.com/vansh28v/q-shield/blob/main/app/api/security/experiment/route.ts"
click node_attack_api "https://github.com/vansh28v/q-shield/blob/main/app/api/security/attack/route.ts"
click node_quantum_api "https://github.com/vansh28v/q-shield/blob/main/app/api/quantum/simulate/route.ts"
click node_auth_api "https://github.com/vansh28v/q-shield/tree/main/app/api/auth"
click node_events_api "https://github.com/vansh28v/q-shield/blob/main/app/api/events/route.ts"
click node_qds_experiment "https://github.com/vansh28v/q-shield/blob/main/lib/security/experiment.ts"
click node_attack_simulation "https://github.com/vansh28v/q-shield/blob/main/lib/quantum/attacks.ts"
click node_quantum_engine "https://github.com/vansh28v/q-shield/blob/main/lib/quantum/simulator.ts"
click node_quantum_primitives "https://github.com/vansh28v/q-shield/blob/main/lib/quantum/state.ts"
click node_quantum_measurement "https://github.com/vansh28v/q-shield/blob/main/lib/quantum/measurement.ts"
click node_signature_verification "https://github.com/vansh28v/q-shield/blob/main/lib/security/signature.ts"
click node_threat_detection "https://github.com/vansh28v/q-shield/blob/main/lib/security/detector.ts"
click node_replay_ledger "https://github.com/vansh28v/q-shield/blob/main/lib/security/ledger.ts"
click node_telemetry "https://github.com/vansh28v/q-shield/blob/main/lib/security/telemetry.ts"
click node_persistence "https://github.com/vansh28v/q-shield/blob/main/lib/security/persistence.ts"
click node_database "https://github.com/vansh28v/q-shield/blob/main/lib/security/db.ts"
click node_session "https://github.com/vansh28v/q-shield/blob/main/lib/security/session.ts"

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_experiment_api,node_attack_api,node_quantum_api,node_auth_api,node_events_api toneBlue
class node_attack_simulation,node_quantum_engine,node_quantum_primitives,node_quantum_measurement toneAmber
class node_qds_experiment,node_signature_verification,node_threat_detection,node_replay_ledger,node_telemetry,node_session toneMint
class node_persistence,node_database toneRose
```

## Components

### API workflows

- [Experiment API](https://github.com/vansh28v/q-shield/blob/main/app/api/security/experiment/route.ts): `app/api/security/experiment/route.ts`
- [Attack API](https://github.com/vansh28v/q-shield/blob/main/app/api/security/attack/route.ts): `app/api/security/attack/route.ts`
- [Quantum API](https://github.com/vansh28v/q-shield/blob/main/app/api/quantum/simulate/route.ts): `app/api/quantum/simulate/route.ts`
- [Authentication API](https://github.com/vansh28v/q-shield/tree/main/app/api/auth): `app/api/auth`
- [Events API](https://github.com/vansh28v/q-shield/blob/main/app/api/events/route.ts): `app/api/events/route.ts`

### Quantum simulation

- [Attack simulation](https://github.com/vansh28v/q-shield/blob/main/lib/quantum/attacks.ts): `lib/quantum/attacks.ts`
- [Quantum engine](https://github.com/vansh28v/q-shield/blob/main/lib/quantum/simulator.ts): `lib/quantum/simulator.ts`
- [Quantum primitives](https://github.com/vansh28v/q-shield/blob/main/lib/quantum/state.ts): `lib/quantum/state.ts`
- [Measurement and statistics](https://github.com/vansh28v/q-shield/blob/main/lib/quantum/measurement.ts): `lib/quantum/measurement.ts`

### Security analysis

- [QDS experiment](https://github.com/vansh28v/q-shield/blob/main/lib/security/experiment.ts): `lib/security/experiment.ts`
- [Signature verification](https://github.com/vansh28v/q-shield/blob/main/lib/security/signature.ts): `lib/security/signature.ts`
- [Threat detection](https://github.com/vansh28v/q-shield/blob/main/lib/security/detector.ts): `lib/security/detector.ts`
- [Replay ledger](https://github.com/vansh28v/q-shield/blob/main/lib/security/ledger.ts): `lib/security/ledger.ts`
- [Experiment telemetry](https://github.com/vansh28v/q-shield/blob/main/lib/security/telemetry.ts): `lib/security/telemetry.ts`
- [Session handling](https://github.com/vansh28v/q-shield/blob/main/lib/security/session.ts): `lib/security/session.ts`

### Persistence

- [Persistence services](https://github.com/vansh28v/q-shield/blob/main/lib/security/persistence.ts): `lib/security/persistence.ts`
- [SQLite database](https://github.com/vansh28v/q-shield/blob/main/lib/security/db.ts): `lib/security/db.ts`

## Connections

- Experiment API → QDS experiment: runs experiment (evidence: `app/api/security/experiment/route.ts`)
- Experiment API → Replay ledger: supplies ledger (evidence: `app/api/security/experiment/route.ts`)
- Experiment API → Experiment telemetry: creates telemetry (evidence: `app/api/security/experiment/route.ts`)
- Experiment API → Persistence services: saves results (evidence: `app/api/security/experiment/route.ts`)
- Attack API → Attack simulation: simulates attack (evidence: `app/api/security/attack/route.ts`)
- Attack API → Persistence services: saves run (evidence: `app/api/security/attack/route.ts`)
- Quantum API → Quantum engine: runs simulation (evidence: `app/api/quantum/simulate/route.ts`)
- Authentication API → Persistence services: manages accounts (evidence: `app/api/auth/signup/route.ts`)
- Authentication API → Session handling: sets session (evidence: `app/api/auth/signup/route.ts`)
- Events API → Persistence services: reads events (evidence: `app/api/events/route.ts`)
- QDS experiment → Quantum engine: runs QDS (evidence: `lib/security/experiment.ts`)
- QDS experiment → Signature verification: creates and verifies (evidence: `lib/security/experiment.ts`)
- QDS experiment → Threat detection: detects threats (evidence: `lib/security/experiment.ts`)
- QDS experiment → Replay ledger: checks replay (evidence: `lib/security/experiment.ts`)
- Attack simulation → Quantum engine: runs experiment (evidence: `lib/quantum/attacks.ts`)
- Attack simulation → Replay ledger: checks replay (evidence: `lib/quantum/attacks.ts`)
- Quantum engine → Quantum primitives: uses state operations (evidence: `lib/quantum/simulator.ts`)
- Quantum engine → Measurement and statistics: measures and analyzes (evidence: `lib/quantum/simulator.ts`)
- Signature verification → Quantum primitives: uses state operations (evidence: `lib/security/signature.ts`)
- Persistence services → SQLite database: reads and writes (evidence: `lib/security/persistence.ts`)
- Replay ledger → SQLite database: stores replay records (evidence: `lib/security/ledger.ts`)
- Session handling → Persistence services: resolves user (evidence: `lib/security/session.ts`)
