# vaishnaviupadyaya/q-shield architecture

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

## Overview

Q-Shield is a research prototype for QDS document signing and verification, plus attack-simulation experiments and security analytics. Its main workflow hashes a document, creates a quantum seal, and verifies it with simulated measurements; the experiment workflow runs a protocol with optional attacks and evaluates measurement statistics. The frontend also exposes authentication, experiment history, and analytics. Edges reflect README descriptions and SOURCE INDEX references; several UI-to-API and unsampled subsystem connections are omitted because their runtime wiring was not shown.

Main entry points: [`backend/routers/documents.py`](https://github.com/vaishnaviupadyaya/q-shield/blob/main/backend/routers/documents.py) (Document endpoints), [`backend/services/experiment_service.py`](https://github.com/vaishnaviupadyaya/q-shield/blob/main/backend/services/experiment_service.py) (Experiment orchestration), [`backend/main.py`](https://github.com/vaishnaviupadyaya/q-shield/blob/main/backend/main.py) (FastAPI application), [`backend/routers/auth.py`](https://github.com/vaishnaviupadyaya/q-shield/blob/main/backend/routers/auth.py) (Authentication routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["User interface"]
  node_web["Web application<br/>[page.jsx]"]
  node_sign_ui["Document signing"]
  node_verify_ui["Document verification"]
  node_simulation_ui["Simulation studio"]
  node_history_ui["Experiment history"]
  node_analytics_ui["Threat analytics"]
  node_auth_ui["Authentication UI<br/>[AuthModal.jsx]"]
end

subgraph group_api["API and identity"]
  node_api["FastAPI application<br/>[main.py]"]
  node_schemas["Request and response schemas<br/>[schemas.py]"]
  node_auth_routes["Authentication routes<br/>[auth.py]"]
  node_auth_service["Authentication service<br/>[auth_service.py]"]
end

subgraph group_document["Document security"]
  node_documents["Document endpoints<br/>[documents.py]"]
  node_hasher["Document hashing<br/>[document_hasher.py]"]
  node_protocol["Quantum signature protocol<br/>[protocol.py]"]
  node_certificate["Verification certificates"]
end

subgraph group_experiment["Threat experiments"]
  node_experiment_routes["Experiment routes<br/>[experiments.py]"]
  node_experiment_service["Experiment orchestration"]
  node_attack_models["Attack scenarios<br/>[attacks.py]"]
  node_attack_types["Attack definitions<br/>[base.py]"]
  node_stats["Measurement statistics<br/>[statistics.py]"]
  node_hypothesis["Statistical tests<br/>[hypothesis.py]"]
end

subgraph group_persistence["Persistence and metrics"]
  node_metrics["Experiment metrics<br/>[metrics.py]"]
  node_history_service["Experiment history service<br/>[history_service.py]"]
  node_store[("Firestore and local storage")]
end

node_user(("Q-Shield user"))

node_user -->|"uses"| node_web
node_web -->|"renders"| node_sign_ui
node_web -->|"renders"| node_verify_ui
node_api -->|"registers"| node_auth_routes
node_api -->|"registers"| node_experiment_routes
node_api -->|"registers"| node_documents
node_auth_routes -->|"calls"| node_auth_service
node_auth_routes -->|"uses"| node_schemas
node_documents -->|"uses"| node_schemas
node_documents -->|"uses"| node_hasher
node_documents -->|"uses"| node_protocol
node_documents -->|"uses"| node_certificate
node_documents -->|"persists documents"| node_store
node_experiment_routes -->|"calls"| node_experiment_service
node_experiment_service -->|"signs and verifies"| node_protocol
node_experiment_service -->|"applies attacks"| node_attack_models
node_experiment_service -->|"compares distributions"| node_stats
node_experiment_service -->|"tests outcomes"| node_hypothesis
node_attack_types -.->|"defines scenarios"| node_attack_models
node_experiment_service -.->|"reports metrics"| node_metrics
node_history_service -->|"persists experiments"| node_store
node_auth_service -->|"reads and writes users"| node_store
node_store -->|"uses metrics"| node_metrics
node_simulation_ui -.->|"configures experiments"| node_experiment_routes
node_history_ui -.->|"requests history"| node_experiment_routes
node_analytics_ui -.->|"requests analytics"| node_api
node_auth_ui -.->|"authenticates"| node_auth_routes

click node_web "https://github.com/vaishnaviupadyaya/q-shield/blob/main/frontend/src/app/page.jsx"
click node_sign_ui "https://github.com/vaishnaviupadyaya/q-shield/blob/main/frontend/src/components/DocumentSigningHub.jsx"
click node_verify_ui "https://github.com/vaishnaviupadyaya/q-shield/blob/main/frontend/src/components/DocumentVerificationHub.jsx"
click node_simulation_ui "https://github.com/vaishnaviupadyaya/q-shield/blob/main/frontend/src/components/SimulationStudio.jsx"
click node_history_ui "https://github.com/vaishnaviupadyaya/q-shield/blob/main/frontend/src/components/ExperimentHistory.jsx"
click node_analytics_ui "https://github.com/vaishnaviupadyaya/q-shield/blob/main/frontend/src/components/ThreatAnalytics.jsx"
click node_auth_ui "https://github.com/vaishnaviupadyaya/q-shield/blob/main/frontend/src/components/auth/AuthModal.jsx"
click node_api "https://github.com/vaishnaviupadyaya/q-shield/blob/main/backend/main.py"
click node_schemas "https://github.com/vaishnaviupadyaya/q-shield/blob/main/backend/schemas.py"
click node_auth_routes "https://github.com/vaishnaviupadyaya/q-shield/blob/main/backend/routers/auth.py"
click node_auth_service "https://github.com/vaishnaviupadyaya/q-shield/blob/main/backend/services/auth_service.py"
click node_documents "https://github.com/vaishnaviupadyaya/q-shield/blob/main/backend/routers/documents.py"
click node_hasher "https://github.com/vaishnaviupadyaya/q-shield/blob/main/quantum/document_hasher.py"
click node_protocol "https://github.com/vaishnaviupadyaya/q-shield/blob/main/quantum/protocol.py"
click node_certificate "https://github.com/vaishnaviupadyaya/q-shield/blob/main/certificates/verification_certificate.py"
click node_experiment_routes "https://github.com/vaishnaviupadyaya/q-shield/blob/main/backend/routers/experiments.py"
click node_experiment_service "https://github.com/vaishnaviupadyaya/q-shield/blob/main/backend/services/experiment_service.py"
click node_attack_models "https://github.com/vaishnaviupadyaya/q-shield/blob/main/detection/attacks.py"
click node_attack_types "https://github.com/vaishnaviupadyaya/q-shield/blob/main/attacks/base.py"
click node_stats "https://github.com/vaishnaviupadyaya/q-shield/blob/main/detection/statistics.py"
click node_hypothesis "https://github.com/vaishnaviupadyaya/q-shield/blob/main/detection/hypothesis.py"
click node_metrics "https://github.com/vaishnaviupadyaya/q-shield/blob/main/experiments/metrics.py"
click node_history_service "https://github.com/vaishnaviupadyaya/q-shield/blob/main/backend/services/history_service.py"
click node_store "https://github.com/vaishnaviupadyaya/q-shield/blob/main/experiments/firestore_storage.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_web,node_sign_ui,node_verify_ui,node_simulation_ui,node_history_ui,node_analytics_ui,node_auth_ui,node_user toneBlue
class node_api,node_schemas,node_auth_routes,node_auth_service toneAmber
class node_documents,node_hasher,node_protocol,node_certificate toneMint
class node_experiment_routes,node_experiment_service,node_attack_models,node_attack_types,node_stats,node_hypothesis toneRose
class node_metrics,node_history_service,node_store toneIndigo
```

## Components

### User interface

- [Web application](https://github.com/vaishnaviupadyaya/q-shield/blob/main/frontend/src/app/page.jsx): `frontend/src/app/page.jsx`
- [Document signing](https://github.com/vaishnaviupadyaya/q-shield/blob/main/frontend/src/components/DocumentSigningHub.jsx): `frontend/src/components/DocumentSigningHub.jsx`
- [Document verification](https://github.com/vaishnaviupadyaya/q-shield/blob/main/frontend/src/components/DocumentVerificationHub.jsx): `frontend/src/components/DocumentVerificationHub.jsx`
- [Simulation studio](https://github.com/vaishnaviupadyaya/q-shield/blob/main/frontend/src/components/SimulationStudio.jsx): `frontend/src/components/SimulationStudio.jsx`
- [Experiment history](https://github.com/vaishnaviupadyaya/q-shield/blob/main/frontend/src/components/ExperimentHistory.jsx): `frontend/src/components/ExperimentHistory.jsx`
- [Threat analytics](https://github.com/vaishnaviupadyaya/q-shield/blob/main/frontend/src/components/ThreatAnalytics.jsx): `frontend/src/components/ThreatAnalytics.jsx`
- [Authentication UI](https://github.com/vaishnaviupadyaya/q-shield/blob/main/frontend/src/components/auth/AuthModal.jsx): `frontend/src/components/auth/AuthModal.jsx`

### API and identity

- [FastAPI application](https://github.com/vaishnaviupadyaya/q-shield/blob/main/backend/main.py): `backend/main.py`
- [Request and response schemas](https://github.com/vaishnaviupadyaya/q-shield/blob/main/backend/schemas.py): `backend/schemas.py`
- [Authentication routes](https://github.com/vaishnaviupadyaya/q-shield/blob/main/backend/routers/auth.py): `backend/routers/auth.py`
- [Authentication service](https://github.com/vaishnaviupadyaya/q-shield/blob/main/backend/services/auth_service.py): `backend/services/auth_service.py`

### Document security

- [Document endpoints](https://github.com/vaishnaviupadyaya/q-shield/blob/main/backend/routers/documents.py): `backend/routers/documents.py`
- [Document hashing](https://github.com/vaishnaviupadyaya/q-shield/blob/main/quantum/document_hasher.py): `quantum/document_hasher.py`
- [Quantum signature protocol](https://github.com/vaishnaviupadyaya/q-shield/blob/main/quantum/protocol.py): `quantum/protocol.py`
- [Verification certificates](https://github.com/vaishnaviupadyaya/q-shield/blob/main/certificates/verification_certificate.py): `certificates/verification_certificate.py`

### Threat experiments

- [Experiment routes](https://github.com/vaishnaviupadyaya/q-shield/blob/main/backend/routers/experiments.py): `backend/routers/experiments.py`
- [Experiment orchestration](https://github.com/vaishnaviupadyaya/q-shield/blob/main/backend/services/experiment_service.py): `backend/services/experiment_service.py`
- [Attack scenarios](https://github.com/vaishnaviupadyaya/q-shield/blob/main/detection/attacks.py): `detection/attacks.py`
- [Attack definitions](https://github.com/vaishnaviupadyaya/q-shield/blob/main/attacks/base.py): `attacks/base.py`
- [Measurement statistics](https://github.com/vaishnaviupadyaya/q-shield/blob/main/detection/statistics.py): `detection/statistics.py`
- [Statistical tests](https://github.com/vaishnaviupadyaya/q-shield/blob/main/detection/hypothesis.py): `detection/hypothesis.py`

### Persistence and metrics

- [Experiment metrics](https://github.com/vaishnaviupadyaya/q-shield/blob/main/experiments/metrics.py): `experiments/metrics.py`
- [Experiment history service](https://github.com/vaishnaviupadyaya/q-shield/blob/main/backend/services/history_service.py): `backend/services/history_service.py`
- [Firestore and local storage](https://github.com/vaishnaviupadyaya/q-shield/blob/main/experiments/firestore_storage.py): `experiments/firestore_storage.py`

### Other components

- **Q-Shield user**

## Connections

- Q-Shield user → Web application: uses (evidence: `README.md`)
- Web application → Document signing: renders (evidence: `frontend/src/app/page.jsx`)
- Web application → Document verification: renders (evidence: `frontend/src/app/page.jsx`)
- FastAPI application → Authentication routes: registers (evidence: `backend/main.py`)
- FastAPI application → Experiment routes: registers (evidence: `backend/main.py`)
- FastAPI application → Document endpoints: registers (evidence: `backend/main.py`)
- Authentication routes → Authentication service: calls (evidence: `backend/routers/auth.py`)
- Authentication routes → Request and response schemas: uses (evidence: `backend/routers/auth.py`)
- Document endpoints → Request and response schemas: uses (evidence: `backend/routers/documents.py`)
- Document endpoints → Document hashing: uses (evidence: `backend/routers/documents.py`)
- Document endpoints → Quantum signature protocol: uses (evidence: `backend/routers/documents.py`)
- Document endpoints → Verification certificates: uses (evidence: `backend/routers/documents.py`)
- Document endpoints → Firestore and local storage: persists documents (evidence: `backend/routers/documents.py`)
- Experiment routes → Experiment orchestration: calls (evidence: `backend/routers/experiments.py`)
- Experiment orchestration → Quantum signature protocol: signs and verifies (evidence: `backend/services/experiment_service.py`)
- Experiment orchestration → Attack scenarios: applies attacks (evidence: `backend/services/experiment_service.py`)
- Experiment orchestration → Measurement statistics: compares distributions (evidence: `backend/services/experiment_service.py`)
- Experiment orchestration → Statistical tests: tests outcomes (evidence: `backend/services/experiment_service.py`)
- Attack definitions → Attack scenarios: defines scenarios
- Experiment orchestration → Experiment metrics: reports metrics
- Experiment history service → Firestore and local storage: persists experiments (evidence: `backend/services/history_service.py`)
- Authentication service → Firestore and local storage: reads and writes users (evidence: `backend/services/auth_service.py`)
- Firestore and local storage → Experiment metrics: uses metrics (evidence: `experiments/firestore_storage.py`)
- Simulation studio → Experiment routes: configures experiments
- Experiment history → Experiment routes: requests history
- Threat analytics → FastAPI application: requests analytics
- Authentication UI → Authentication routes: authenticates
