# neha-george/_bb84_ architecture

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

- Interactive diagram: https://gitdiagram.com/neha-george/_bb84_
- Repository: https://github.com/neha-george/_bb84_

## Overview

QSafe BB84 is organized as a two-tier simulation system: a Python Flask backend that owns the BB84 protocol state and simulation logic, and a React/TypeScript frontend that renders the protocol lifecycle, controls the simulation, and visualizes results. The repo is not split into independent microservices; instead, the backend is a single API host with multiple protocol-oriented modules, and the frontend is a single-page app that talks to it over HTTP.

At a high level, the architecture has these boundaries:

1. Presentation layer: the React/Vite app under `client/`
2. Protocol engine and API layer: the Flask app in `app.py` plus supporting Python modules
3. Simulation and security primitives: key generation, noise models, reconciliation, privacy amplification
4. Peer/network and messaging layer: connection, sync, and encrypted chat endpoints
5. Verification/test harness: standalone Python scripts that exercise the backend flows end-to-end

Backend structure

The backend entry point is `app.py`. It exposes the REST API used by the UI and by the verification scripts. The backend appears stateful: it tracks Alice/Bob session state, quantum data, noise configuration, key lifecycle status, and peer connection state across requests. That state is likely stored in module-level objects or in session-like structures rather than in a separate database, because the repo contains no persistent datastore layer.

The protocol-specific backend modules are split by responsibility:

- `alice.py` and `bob.py` encapsulate the two protocol roles. They likely manage role-specific state such as generated bits, basis choices, measurements, and key status.
- `node.py` represents a peer or network node abstraction used for P2P synchronization and message exchange.
- `randomkey.py` handles random bit/key generation.
- `noise_simulator.py` models channel noise, packet loss, interception density, and other attack-like conditions.
- `cascade.py` implements reconciliation via Cascade parity checks, block sizing, and error localization/correction.
- `privacy.py` performs privacy amplification and leakage-aware shrinking of reconciled keys.
- `recursive_session.py` supports the recursive BB84 mode, where previous rounds influence the next round’s bias/behavior.

This backend is simulation-heavy rather than hardware-integrated. Qiskit and Qiskit Aer are listed as core dependencies, so the “quantum channel” is represented by simulated qubit preparation/measurement behavior, not real quantum network hardware.

Frontend structure

The frontend is a separate Vite-based React application in `client/`. `App.tsx` composes the interface, while `ProjectContext.tsx` provides shared UI state for protocol data, metrics, logs, and connection status.

The main UI is broken into protocol-centric panels/components rather than generic pages:

- `ProjectOverview.tsx` explains the system and protocol stages
- `ConnectionPanel.tsx` handles peer connect/disconnect and network setup
- `AlicePanel.tsx` and `BobPanel.tsx` show the two role-specific sides of the BB84 flow
- `CascadeVisualizer.tsx` renders reconciliation steps and mismatch correction flow
- `SecurityMetrics.tsx` surfaces QBER, thresholds, and verification status
- `RecursiveBB84.tsx` exposes recursive session mode and round-based state
- `ChatInterface.tsx` handles secure messaging after key establishment
- `LogTerminal.tsx` and `Messaging.tsx` present protocol logs and message traffic
- `KeyLifecycleFunnel.tsx` and `ProtocolComparison.tsx` visualize key state and protocol behavior

The frontend is effectively a control room for the backend simulator. User actions in the UI trigger API calls, and the returned JSON drives the dashboards, logs, visualizations, and status indicators.

Core end-to-end data flow

The main protocol flow runs from Alice generation to Bob verification, with several branches depending on QBER and network conditions:

- The user initiates key generation from the frontend.
- Flask endpoints create Alice’s raw bits and basis choices, then produce the simulated quantum data.
- Bob measures using his own basis choices.
- The system performs public sifting to remove mismatched bases.
- A QBER check determines whether the session is acceptable.
- If the error rate is within threshold, the system proceeds to Cascade reconciliation and then privacy amplification.
- If the error rate is too high, the backend aborts and classifies the failure, distinguishing security threats from environmental or software issues.
- Once a secure key exists, the chat and encryption endpoints can use it for message exchange.
- In peer-to-peer mode, one node can initiate, connect, fetch state from the other peer, and synchronize keys.

That means the architectural split is not “frontend versus backend” only; there is also an internal split between “public classical channel” operations and “quantum channel” simulation. Sifting, verification, and some messaging happen on the public side, while state preparation, measurement, and attack/noise modeling belong to the quantum/simulated side.

API and state boundaries

The API surface is explicitly grouped by function:

- Configuration and metrics endpoints manage noise, attack mode, and key metrics
- Core BB84 endpoints handle generation, measurement, sifting, verification, sampling, and finalization
- Network endpoints handle peer initiation, connection, status, disconnection, and fetching remote state
- QKD/messaging endpoints support quick generation, P2P sync, encryption, decryption, and message retrieval
- Chat endpoints support send/receive/clear flows
- Recursive endpoints expose recursive session status and seed/message operations
- Eve utilities expose interception behavior for attack simulation

This grouping suggests the backend is acting as a protocol state machine exposed over HTTP. The UI advances the state machine step-by-step, and the backend returns protocol artifacts and telemetry.

Security and failure handling

A notable architectural feature is the classification of aborts. The backend does not treat all failures as the same. Instead, it distinguishes:

- `security_threat`
- `environmental_noise`
- `software_error`

That classification matters for the UI and for the control flow, because environmental noise may route the user into reconciliation, while a true security threat should abort the session. The repo also includes support for short-key and edge-case handling in privacy amplification so tiny outputs do not crash the flow.

Testing and verification layer

The root-level test and verify scripts are an important part of the architecture. They are not unit tests in the narrow sense; they are executable workflow checks that validate backend behavior over HTTP and simulate real protocol sequences:

- `test_flow.py`
- `test_advanced_noise.py`
- `test_chat.py`
- `test_chat_stateless.py`
- `test_p2p_sync.py`
- `verify_full_flow.py`
- `verify_network_error.py`
- `verify_network_sifting.py`
- `verify_quantum_channel.py`
- `verify_sifting.py`
- `verify_dbs_sync.py`

These scripts form an external validation harness around the Flask API and are useful to think of as a third boundary: they exercise the system like a client, but without the UI.

Infrastructure and runtime implications

The system is designed to run locally with two processes:
- Flask backend on port 5000
- Vite frontend on port 5173

CORS is therefore relevant because the frontend and backend are separate origins during development. The backend depends on Python 3.10+, Flask, Flask-CORS, NumPy/SciPy, Qiskit/Qiskit Aer, and Requests; the frontend depends on Node.js, React, TypeScript, Vite, Axios, Framer Motion, and Lucide React.

In diagram terms, the most important boxes are:
- React UI
- Flask API
- BB84 role/state modules
- Channel/noise simulation
- Cascade reconciliation
- Privacy amplification
- Peer sync / messaging
- Test/verification scripts

The most important arrows are:
- UI actions to Flask API requests
- API responses back to UI state/context
- Quantum simulation flow from Alice to Bob to sifting/verification
- Reconciliation and privacy amplification after successful QBER checks
- Peer sync and chat flow after key establishment
- Verification scripts hitting the same API as the UI

Overall, this repository is a protocol simulator with a stateful backend engine and a componentized operational dashboard, rather than a generic CRUD application or a simple demo page.

Main entry points: [`app.py`](https://github.com/neha-george/_bb84_/blob/HEAD/app.py) (Flask API), [`client/src/App.tsx`](https://github.com/neha-george/_bb84_/blob/HEAD/client/src/App.tsx) (App), [`alice.py`](https://github.com/neha-george/_bb84_/blob/HEAD/alice.py) (Alice), [`bob.py`](https://github.com/neha-george/_bb84_/blob/HEAD/bob.py) (Bob)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph "Frontend"
  client_app["App<br/>React SPA shell<br/>[App.tsx]"]
  client_ctx(("Context<br/>UI state<br/>[ProjectContext.tsx]"))
  ui_overview["Overview<br/>ui panel"]
  ui_connection["Connection<br/>ui panel"]
  ui_roles["Alice/Bob<br/>ui panels<br/>[AlicePanel.tsx]"]
  ui_cascade["Cascade View<br/>ui visualizer"]
  ui_security["Security Metrics<br/>ui dashboard"]
  ui_recursive["Recursive BB84<br/>ui control<br/>[RecursiveBB84.tsx]"]
  ui_chat["Chat<br/>ui panel<br/>[ChatInterface.tsx]"]
  ui_logs["Logs<br/>ui terminal<br/>[LogTerminal.tsx]"]
  ui_lifecycle["Key Funnel<br/>ui visualizer"]
end

subgraph "Backend"
  api_app["Flask API<br/>protocol API<br/>[app.py]"]
  role_alice(("Alice<br/>role state<br/>[alice.py]"))
  role_bob(("Bob<br/>role state<br/>[bob.py]"))
  sim_random(("Random Key<br/>generator<br/>[randomkey.py]"))
  sim_noise{{"Noise Sim<br/>channel model<br/>[noise_simulator.py]"}}
  sim_cascade{{"Cascade<br/>reconciliation<br/>[cascade.py]"}}
  sim_privacy{{"Privacy<br/>amplification<br/>[privacy.py]"}}
  sim_recursive(("Recursive Session<br/>session model"))
  peer_node[("Node<br/>peer sync<br/>[node.py]")]
end

subgraph "Validation"
  verify_flow["Flow Tests<br/>workflow checks<br/>[test_flow.py]"]
  verify_network["Network Checks<br/>workflow checks"]
  verify_quantum["Quantum Checks<br/>workflow checks"]
  verify_chat["Chat Checks<br/>workflow checks<br/>[test_chat.py]"]
end

client_app -->|"uses"| client_ctx
client_app -->|"renders"| ui_overview
client_app -->|"renders"| ui_connection
client_app -->|"renders"| ui_roles
client_app -->|"renders"| ui_cascade
client_app -->|"renders"| ui_security
client_app -->|"renders"| ui_recursive
client_app -->|"renders"| ui_chat
client_app -->|"renders"| ui_logs
client_app -->|"renders"| ui_lifecycle
client_ctx -->|"calls"| api_app
api_app -->|"orchestrates"| role_alice
api_app -->|"orchestrates"| role_bob
api_app -->|"generates"| sim_random
api_app -->|"simulates"| sim_noise
api_app -->|"reconciles"| sim_cascade
api_app -->|"shrinks"| sim_privacy
api_app -->|"tracks"| sim_recursive
api_app -->|"syncs"| peer_node
role_alice -->|"feeds"| role_bob
role_alice -->|"passes through"| sim_noise
role_bob -->|"verifies"| sim_cascade
sim_cascade -->|"inputs"| sim_privacy
peer_node -->|"enables"| ui_chat
api_app -->|"exercised by"| verify_flow
api_app -->|"exercised by"| verify_network
api_app -->|"exercised by"| verify_quantum
api_app -->|"exercised by"| verify_chat

click client_app "https://github.com/neha-george/_bb84_/blob/master/client/src/App.tsx"
click client_ctx "https://github.com/neha-george/_bb84_/blob/master/client/src/context/ProjectContext.tsx"
click ui_overview "https://github.com/neha-george/_bb84_/blob/master/client/src/components/ProjectOverview.tsx"
click ui_connection "https://github.com/neha-george/_bb84_/blob/master/client/src/components/ConnectionPanel.tsx"
click ui_roles "https://github.com/neha-george/_bb84_/blob/master/client/src/components/AlicePanel.tsx"
click ui_cascade "https://github.com/neha-george/_bb84_/blob/master/client/src/components/CascadeVisualizer.tsx"
click ui_security "https://github.com/neha-george/_bb84_/blob/master/client/src/components/SecurityMetrics.tsx"
click ui_recursive "https://github.com/neha-george/_bb84_/blob/master/client/src/components/RecursiveBB84.tsx"
click ui_chat "https://github.com/neha-george/_bb84_/blob/master/client/src/components/ChatInterface.tsx"
click ui_logs "https://github.com/neha-george/_bb84_/blob/master/client/src/components/LogTerminal.tsx"
click ui_lifecycle "https://github.com/neha-george/_bb84_/blob/master/client/src/components/KeyLifecycleFunnel.tsx"
click api_app "https://github.com/neha-george/_bb84_/blob/master/app.py"
click role_alice "https://github.com/neha-george/_bb84_/blob/master/alice.py"
click role_bob "https://github.com/neha-george/_bb84_/blob/master/bob.py"
click sim_random "https://github.com/neha-george/_bb84_/blob/master/randomkey.py"
click sim_noise "https://github.com/neha-george/_bb84_/blob/master/noise_simulator.py"
click sim_cascade "https://github.com/neha-george/_bb84_/blob/master/cascade.py"
click sim_privacy "https://github.com/neha-george/_bb84_/blob/master/privacy.py"
click sim_recursive "https://github.com/neha-george/_bb84_/blob/master/recursive_session.py"
click peer_node "https://github.com/neha-george/_bb84_/blob/master/node.py"
click verify_flow "https://github.com/neha-george/_bb84_/blob/master/test_flow.py"
click verify_network "https://github.com/neha-george/_bb84_/blob/master/verify_network_error.py"
click verify_quantum "https://github.com/neha-george/_bb84_/blob/master/verify_quantum_channel.py"
click verify_chat "https://github.com/neha-george/_bb84_/blob/master/test_chat.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 client_app,client_ctx,ui_overview,ui_connection,ui_roles,ui_cascade,ui_security,ui_recursive,ui_chat,ui_logs,ui_lifecycle toneBlue
class api_app,role_alice,role_bob,sim_random,sim_noise,sim_cascade,sim_privacy,sim_recursive,peer_node toneAmber
class verify_flow,verify_network,verify_quantum,verify_chat toneMint
```

## Components

### Frontend

React/Vite presentation layer

- [App](https://github.com/neha-george/_bb84_/blob/HEAD/client/src/App.tsx): React SPA shell · Top-level frontend composition and routing shell · `client/src/App.tsx`
- [Context](https://github.com/neha-george/_bb84_/blob/HEAD/client/src/context/ProjectContext.tsx): UI state · Shared UI state for protocol data, logs, and connection status · `client/src/context/ProjectContext.tsx`
- [Overview](https://github.com/neha-george/_bb84_/blob/HEAD/client/src/components/ProjectOverview.tsx): ui panel · System introduction and protocol stage summary · `client/src/components/ProjectOverview.tsx`
- [Connection](https://github.com/neha-george/_bb84_/blob/HEAD/client/src/components/ConnectionPanel.tsx): ui panel · Peer connect/disconnect and network setup controls · `client/src/components/ConnectionPanel.tsx`
- [Alice/Bob](https://github.com/neha-george/_bb84_/blob/HEAD/client/src/components/AlicePanel.tsx): ui panels · Role-specific protocol views for Alice and Bob · `client/src/components/AlicePanel.tsx`
- [Cascade View](https://github.com/neha-george/_bb84_/blob/HEAD/client/src/components/CascadeVisualizer.tsx): ui visualizer · Reconciliation and mismatch correction visualization · `client/src/components/CascadeVisualizer.tsx`
- [Security Metrics](https://github.com/neha-george/_bb84_/blob/HEAD/client/src/components/SecurityMetrics.tsx): ui dashboard · QBER, thresholds, and verification status display · `client/src/components/SecurityMetrics.tsx`
- [Recursive BB84](https://github.com/neha-george/_bb84_/blob/HEAD/client/src/components/RecursiveBB84.tsx): ui control · Recursive session mode and round state controls · `client/src/components/RecursiveBB84.tsx`
- [Chat](https://github.com/neha-george/_bb84_/blob/HEAD/client/src/components/ChatInterface.tsx): ui panel · Secure messaging interface after key establishment · `client/src/components/ChatInterface.tsx`
- [Logs](https://github.com/neha-george/_bb84_/blob/HEAD/client/src/components/LogTerminal.tsx): ui terminal · Protocol logs and message activity display · `client/src/components/LogTerminal.tsx`
- [Key Funnel](https://github.com/neha-george/_bb84_/blob/HEAD/client/src/components/KeyLifecycleFunnel.tsx): ui visualizer · Key lifecycle and status progression view · `client/src/components/KeyLifecycleFunnel.tsx`

### Backend

Flask protocol engine and simulation modules

- [Flask API](https://github.com/neha-george/_bb84_/blob/HEAD/app.py): protocol API · Stateful HTTP host for BB84 operations and endpoints · `app.py`
- [Alice](https://github.com/neha-george/_bb84_/blob/HEAD/alice.py): role state · Alice-side protocol state and generation logic · `alice.py`
- [Bob](https://github.com/neha-george/_bb84_/blob/HEAD/bob.py): role state · Bob-side protocol state and measurement logic · `bob.py`
- [Random Key](https://github.com/neha-george/_bb84_/blob/HEAD/randomkey.py): generator · Random bit and key generation · `randomkey.py`
- [Noise Sim](https://github.com/neha-george/_bb84_/blob/HEAD/noise_simulator.py): channel model · Channel noise, loss, and interception simulation · `noise_simulator.py`
- [Cascade](https://github.com/neha-george/_bb84_/blob/HEAD/cascade.py): reconciliation · Parity-based error correction and reconciliation · `cascade.py`
- [Privacy](https://github.com/neha-george/_bb84_/blob/HEAD/privacy.py): amplification · Privacy amplification and leakage reduction · `privacy.py`
- [Recursive Session](https://github.com/neha-george/_bb84_/blob/HEAD/recursive_session.py): session model · Recursive BB84 round management and prior-state influence · `recursive_session.py`
- [Node](https://github.com/neha-george/_bb84_/blob/HEAD/node.py): peer sync · Peer/network abstraction for synchronization and messaging · `node.py`

### Validation

Executable end-to-end verification scripts

- [Flow Tests](https://github.com/neha-george/_bb84_/blob/HEAD/test_flow.py): workflow checks · Executable end-to-end protocol flow validation scripts · `test_flow.py`
- [Network Checks](https://github.com/neha-george/_bb84_/blob/HEAD/verify_network_error.py): workflow checks · Network, sync, and error-path verification scripts · `verify_network_error.py`
- [Quantum Checks](https://github.com/neha-george/_bb84_/blob/HEAD/verify_quantum_channel.py): workflow checks · Quantum-channel and sifting verification scripts · `verify_quantum_channel.py`
- [Chat Checks](https://github.com/neha-george/_bb84_/blob/HEAD/test_chat.py): workflow checks · Chat and P2P message flow verification scripts · `test_chat.py`

## Connections

- App → Context: uses · App consumes shared UI state
- App → Overview: renders · Main shell composes overview panel
- App → Connection: renders · Main shell composes connection controls
- App → Alice/Bob: renders · Main shell composes role panels
- App → Cascade View: renders · Main shell composes reconciliation view
- App → Security Metrics: renders · Main shell composes security dashboard
- App → Recursive BB84: renders · Main shell composes recursive mode controls
- App → Chat: renders · Main shell composes messaging interface
- App → Logs: renders · Main shell composes log terminal
- App → Key Funnel: renders · Main shell composes key lifecycle view
- Context → Flask API: calls · UI state is populated from backend responses
- Flask API → Alice: orchestrates · Backend coordinates Alice-side protocol state
- Flask API → Bob: orchestrates · Backend coordinates Bob-side protocol state
- Flask API → Random Key: generates · Backend creates random bits and keys
- Flask API → Noise Sim: simulates · Backend applies channel noise and attack conditions
- Flask API → Cascade: reconciles · Backend invokes Cascade error correction
- Flask API → Privacy: shrinks · Backend performs privacy amplification
- Flask API → Recursive Session: tracks · Backend manages recursive session behavior
- Flask API → Node: syncs · Backend exposes peer connection and state exchange
- Alice → Bob: feeds · Alice state drives Bob measurement and comparison flow
- Alice → Noise Sim: passes through · Prepared bits traverse the noisy simulated channel
- Bob → Cascade: verifies · Bob-side outcomes feed reconciliation
- Cascade → Privacy: inputs · Reconciled key is reduced by privacy amplification
- Node → Chat: enables · Established peer state supports secure chat
- Flask API → Flow Tests: exercised by · Verification scripts hit the same API as the UI
- Flask API → Network Checks: exercised by · Network scripts validate connection and error paths
- Flask API → Quantum Checks: exercised by · Quantum scripts validate sifting and channel behavior
- Flask API → Chat Checks: exercised by · Chat scripts validate encrypted messaging flows
