# aaronmcleancs/fidelitychain architecture

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

- Interactive diagram: https://gitdiagram.com/aaronmcleancs/fidelitychain
- Repository: https://github.com/aaronmcleancs/fidelitychain

## Overview

##### Main Components
- Blockchain Core: Represent the essential blockchain entities including Transaction, Block, and Blockchain (ledger update process).
- Quantum Components: Include components unique to the quantum-assisted consensus such as:
- QuantumRandomNumberGenerator (for random number generation using quantum circuits)
- QuantumHashFunction (for mapping data to quantum states)
- QuantumTeleportation (to share quantum states among nodes)
- FidelityChecker (for computing similarity metrics between quantum states)
- QuantumConsensusProtocol and QuantumConsensusNode (which coordinate and execute the quantum consensus process)
- Classical Components: Represent elements specific to the classical blockchain simulation:
- ClassicalConsensusNode
- ClassicalConsensusProtocol (which leverage proof-of-work)
- Simulation / CLI: The cli.py acts as an entry point for triggering simulations (both quantum and classical) and can be shown as the orchestration layer.

##### Relationships and Data Flow
- How the simulation initializes nodes (both quantum and classical) and distributes transactions.
- Parallel execution paths:
- In the quantum branch, emphasize the flow from quantum random number generation, candidate block creation, mapping blocks to quantum states, sharing these states between nodes, calculating fidelity, and finally selecting the winning block.
- In the classical branch, show how proof-of-work is computed to choose the block.
- Interactions where both protocols may run concurrently or be compared against one another to demonstrate advantages of the quantum approach over classical methods.

##### Architectural Patterns and Design Principles
- External Libraries and Dependencies: Indicate auxiliary dependencies such as Qiskit, Qiskit Aer, and NumPy as external modules that support quantum computations.

##### Relevant Technology and Framework Details
- Python: The project is implemented in Python 3.7+.

##### Specific Elements
- Labels: Clearly label blockchain core components, quantum-specific modules, classical consensus modules, and simulation control.
- From Transaction Generation → Block Creation → Quantum State Preparation.
- From Quantum State Sharing → Fidelity Calculation → Consensus decision.
- For the classical path, from Candidate Block → Proof-of-Work Verification → Consensus decision.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Simulation Control
    subgraph "Simulation Control"
        CLI("CLI (Simulation)"):::simulation
    end

    %% Blockchain Core
    subgraph "Blockchain Core"
        T("Transaction Generation"):::blockchain
        B("Block Creation"):::blockchain
        L("Ledger Update"):::blockchain
    end

    %% Consensus Process
    subgraph "Consensus Process"
        %% Quantum Consensus Branch
        subgraph "Quantum Consensus"
            QRNG("QuantumRandomNumberGenerator"):::quantum
            QHash("QuantumHashFunction"):::quantum
            QTele("QuantumTeleportation"):::quantum
            FC("FidelityChecker"):::quantum
            QCons("QuantumConsensusProtocol & Node"):::quantum
            UMLQ("UML QuantumChain"):::uml
        end
        %% Classical Consensus Branch
        subgraph "Classical Consensus"
            CCons("ClassicalConsensusProtocol & Node"):::classical
            UMLC("UML ClassicalChain"):::uml
        end
    end

    %% External Dependencies for Quantum Computations
    subgraph "External Dependencies"
        Qiskit("Qiskit"):::external
        QiskitAer("Qiskit Aer"):::external
        NumPy("NumPy"):::external
    end

    %% UML Artifacts common
    UMLP("UML Protocol"):::uml

    %% Connections
    CLI --> T
    T --> B
    B -->|quantum_path| QRNG
    B -->|classical_path| CCons

    QRNG --> QHash
    QHash --> QTele
    QTele --> FC
    FC --> QCons
    QCons --> L
    CCons --> L

    %% Link External Dependencies for Quantum Operations
    QTele -->|"uses"| Qiskit
    QTele -->|"simulated_by"| QiskitAer
    QHash -->|"with"| NumPy

    %% Connect UML Artifacts
    QCons --- UMLQ
    CCons --- UMLC
    L --- UMLP

    %% Click Events
    click CLI "https://github.com/aaronmcleancs/fidelitychain/blob/main/cli.py"
    click QCons "https://github.com/aaronmcleancs/fidelitychain/blob/main/quantumchain.py"
    click CCons "https://github.com/aaronmcleancs/fidelitychain/blob/main/classicalchain.py"
    click UMLP "https://github.com/aaronmcleancs/fidelitychain/blob/main/UML/protocol.mmd"
    click UMLQ "https://github.com/aaronmcleancs/fidelitychain/blob/main/UML/quantumchain.mmd"
    click UMLC "https://github.com/aaronmcleancs/fidelitychain/blob/main/UML/classical.mmd"

    %% Styles
    classDef simulation fill:#FFD700,stroke:#DAA520,stroke-width:2px;
    classDef blockchain fill:#D3D3D3,stroke:#808080,stroke-width:2px;
    classDef quantum fill:#ADD8E6,stroke:#0000FF,stroke-width:2px;
    classDef classical fill:#90EE90,stroke:#008000,stroke-width:2px;
    classDef uml fill:#FFA07A,stroke:#FF4500,stroke-width:2px;
    classDef external fill:#E6E6FA,stroke:#9400D3,stroke-width:2px;
```
