How neha-george/_bb84_ works
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 Flask API · App.tsx App · alice.py Alice · bob.py Bob
Components 24
Frontend
React/Vite presentation layer
- App · Top-level frontend composition and routing shell
client/src/App.tsx - Context · Shared UI state for protocol data, logs, and connection status
client/src/context/ProjectContext.tsx - Overview · System introduction and protocol stage summary
client/src/components/ProjectOverview.tsx - Connection · Peer connect/disconnect and network setup controls
client/src/components/ConnectionPanel.tsx - Alice/Bob · Role-specific protocol views for Alice and Bob
client/src/components/AlicePanel.tsx - Cascade View · Reconciliation and mismatch correction visualization
client/src/components/CascadeVisualizer.tsx - Security Metrics · QBER, thresholds, and verification status display
client/src/components/SecurityMetrics.tsx - Recursive BB84 · Recursive session mode and round state controls
client/src/components/RecursiveBB84.tsx - Chat · Secure messaging interface after key establishment
client/src/components/ChatInterface.tsx - Logs · Protocol logs and message activity display
client/src/components/LogTerminal.tsx - Key Funnel · Key lifecycle and status progression view
client/src/components/KeyLifecycleFunnel.tsx
Backend
Flask protocol engine and simulation modules
- Flask API · Stateful HTTP host for BB84 operations and endpoints
app.py - Alice · Alice-side protocol state and generation logic
alice.py - Bob · Bob-side protocol state and measurement logic
bob.py - Random Key · Random bit and key generation
randomkey.py - Noise Sim · Channel noise, loss, and interception simulation
noise_simulator.py - Cascade · Parity-based error correction and reconciliation
cascade.py - Privacy · Privacy amplification and leakage reduction
privacy.py - Recursive Session · Recursive BB84 round management and prior-state influence
recursive_session.py - Node · Peer/network abstraction for synchronization and messaging
node.py
Validation
Executable end-to-end verification scripts
- Flow Tests · Executable end-to-end protocol flow validation scripts
test_flow.py - Network Checks · Network, sync, and error-path verification scripts
verify_network_error.py - Quantum Checks · Quantum-channel and sifting verification scripts
verify_quantum_channel.py - Chat Checks · Chat and P2P message flow verification scripts
test_chat.py
Connections 28
- 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