# trvorth/qanto architecture

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

- Interactive diagram: https://gitdiagram.com/trvorth/qanto
- Repository: https://github.com/trvorth/qanto

## Overview

##### Project Type and Purpose
- This is a production-grade, full-stack Layer-0 blockchain protocol implementation in Rust with ancillary tools (CLI, explorer, relayer), documentation (website, Docusaurus), Helm charts for Kubernetes, and Docker artifacts.
- Purpose: Provide a highly performant, post-quantum-secure, hybrid PoW+DPoS blockchain node (Qanto), accompanying wallet and CLI utilities, network relayer, and web documentation.

##### File Structure Analysis
- Top-Level Cargo Workspace (Cargo.toml, src/): Core node logic, consensus, p2p, DAG ledger, mining, wallet, zk circuits, AI governance.
- myblockchain/: Separate crate housing low-level PoW algorithms (qanhash, GPU kernels), P2P runtime, and benches.
- src/bin/: Executables (qanto-node, wallet CLI, test harnesses, monitor).
- tools/relayer/: Cross-chain relayer service.
- qanto-docs/: Docusaurus-based docs site (API reference, tutorials, whitepaper).
- website/: Static single-page site with Dockerfile and nginx config.
- helm/: Kubernetes charts for api service, boot-node, website.
- config.toml, .env.example: Node configuration.
- docs/: Architecture guides, deployment strategies, security plans.

a. Core Node Service
- Subcomponents: Consensus Engine (PoW+DPoS+PoSe+SAGA AI), QantoDAG ledger, P2P networking (libp2p), Mining Module (CPU/GPU), Transaction Mempool, Wallet Manager.
- Persistence: RocksDB or file store for chain state, UTXOs.
b. API Layer
- REST Server (JSON-RPC), WebSocket server, HTTP port (8545), WS port (8546).
- SDK integrations (JavaScript, Python, Rust).
c. CLI Tools
- qanto-node binary, qantowallet CLI, saga assistant, monitor.
d. Cross-Chain Infrastructure
- Relayer service (tools/relayer) connecting to external blockchains via bridges (Ethereum, Bitcoin, Cosmos, etc.), atomic-swap engine, IBC module.
e. Auxiliary Services
- Explorer (qanto-explorer.html), Documentation site (qanto-docs), Static website.
- Kubernetes deployment using Helm charts (api, boot-node, website).
- Docker containers for node, docs, website.

##### Relationships and Data Flows
- Node ↔ P2P Network: gossip blocks/transactions over libp2p.
- Node ↔ Consensus Engine: consensus module submits blocks to DAG ledger.
- Node ↔ Storage: chain state persisted to RocksDB.
- Client ↔ API Layer: REST/WebSocket requests → Node.
- CLI Tools ↔ Node: RPC calls to start node, submit txs, query chain.
- SDK ↔ API Layer: programmatic access for dApps and integrations.
- Relayer ↔ Node & External Chains: listens for cross-chain events, executes swaps.
- Explorer & Website ↔ API Layer: fetch chain data for UI.
- Helm/K8s ↔ Docker Images: deploy Node and related services in cluster.

##### Architectural Patterns and Design Principles
- Modular Rust crates (separation of concerns).
- Plugin-style cryptography (feature-gated zk circuits).
- Hybrid consensus (PoW for leader election, DPoS for production, PoSe for resource verification, AI-driven security).
- DAG-based sharded ledger for parallel execution.
- Microservices style for relayer, docs site, explorer.
- Infrastructure as code (Helm, Terraform, Docker).

##### Essential Elements
- Clear labels: “Consensus Engine (PoW+DPoS+SAGA)”, “QantoDAG Ledger”, “API Server (REST/WebSocket)”, “Relayer (IBC & Bridges)”.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% On-Chain Core Layer
    subgraph "On-Chain Core" 
        direction TB
        NodeService["Core Node Service<br/>(Rust Cargo Workspace)"]:::core
        Consensus["Consensus Engine<br/>(PoW+DPoS+PoSe+SAGA AI)"]:::core
        DAG["QantoDAG Ledger"]:::core
        P2P["P2P Networking<br/>(libp2p)"]:::core
        Mempool["Transaction Mempool"]:::core
        Miner["Mining Module<br/>(CPU/GPU)"]:::core
        WalletMgr["Wallet Manager"]:::core
        Storage["Chain State Storage<br/>(RocksDB)"]:::core
    end

    %% API Layer
    subgraph "API & SDK Layer"
        direction TB
        APIServer["API Server<br/>(REST/WebSocket)"]:::offchain
        SDK["SDK Integrations<br/>(JS, Python, Rust)"]:::offchain
    end

    %% CLI Tools
    subgraph "CLI Tools"
        direction TB
        CLI1["qanto-node Binary"]:::offchain
        CLI2["qantowallet CLI"]:::offchain
        CLI3["saga assistant"]:::offchain
        CLI4["monitor"]:::offchain
    end

    %% Cross-Chain Infrastructure
    subgraph "Cross-Chain Relayer"
        direction TB
        Relayer["Relayer Service<br/>(IBC & Bridges)"]:::offchain
    end

    %% Auxiliary Services
    subgraph "Auxiliary Services"
        direction TB
        Explorer["Explorer UI"]:::offchain
        Docs["Documentation Site"]:::offchain
        Website["Static Website"]:::offchain
    end

    %% External Networks
    subgraph "External Blockchains" 
        direction TB
        ETH["Ethereum"]:::external
        BTC["Bitcoin"]:::external
        COS["Cosmos"]:::external
    end

    %% Deployment Infrastructure
    subgraph "Deployment Infra"
        direction TB
        Docker["Docker Images"]:::infra
        K8s["Kubernetes (Helm Charts)"]:::infra
    end

    %% Data Flows
    NodeService -->|"uses"| Consensus
    Consensus -->|"submits blocks"| DAG
    NodeService -->|"gossip txs/blocks"| P2P
    NodeService -->|"stores state"| Storage
    NodeService -->|"queues txs"| Mempool
    NodeService -->|"mines blocks"| Miner
    NodeService -->|"manages keys"| WalletMgr

    SDK -->|"calls RPC"| APIServer
    APIServer -->|"forwards requests"| NodeService
    CLI1 -->|"RPC calls"| NodeService
    CLI2 -->|"RPC calls"| NodeService
    CLI3 -->|"RPC calls"| NodeService
    CLI4 -->|"RPC calls"| NodeService

    Relayer -->|"listens/events"| NodeService
    Relayer -->|"bridges"| ETH
    Relayer -->|"bridges"| BTC
    Relayer -->|"bridges"| COS

    Explorer -->|"queries"| APIServer
    Website -->|"fetches data"| APIServer
    Docs -->|"serves docs"| Website

    Docker -->|"packages"| NodeService
    Docker -->|"packages"| APIServer
    Docker -->|"packages"| Website
    K8s -->|"deploys"| Docker

    %% Click Events - Core Node Service & Components
    click NodeService "https://github.com/trvorth/qanto/tree/main/src/"
    click Consensus "https://github.com/trvorth/qanto/blob/main/src/consensus.rs"
    click Consensus "https://github.com/trvorth/qanto/blob/main/src/emission.rs"
    click Consensus "https://github.com/trvorth/qanto/blob/main/src/saga.rs"
    click Consensus "https://github.com/trvorth/qanto/blob/main/src/hame.rs"
    click Consensus "https://github.com/trvorth/qanto/blob/main/src/infinite_strata_node.rs"
    click DAG "https://github.com/trvorth/qanto/blob/main/src/qantodag.rs"
    click DAG "https://github.com/trvorth/qanto/blob/main/src/qantodag_testnet.rs"
    click P2P "https://github.com/trvorth/qanto/blob/main/src/p2p.rs"
    click Mempool "https://github.com/trvorth/qanto/blob/main/src/mempool.rs"
    click Miner "https://github.com/trvorth/qanto/blob/main/src/miner.rs"
    click Miner "https://github.com/trvorth/qanto/blob/main/src/mining_celebration.rs"
    click Miner "https://github.com/trvorth/qanto/blob/main/src/mining_kernel.cl"
    click Miner "https://github.com/trvorth/qanto/blob/main/myblockchain/src/qanhash.rs"
    click Miner "https://github.com/trvorth/qanto/blob/main/myblockchain/src/qanhash32x.rs"
    click Miner "https://github.com/trvorth/qanto/blob/main/myblockchain/src/kernel.cl"
    click WalletMgr "https://github.com/trvorth/qanto/blob/main/src/wallet.rs"
    click WalletMgr "https://github.com/trvorth/qanto/blob/main/src/bin/qantowallet.rs"

    %% API Layer click
    click APIServer "https://github.com/trvorth/qanto/blob/main/myblockchain/src/jsonrpc_server.rs"

    %% CLI Tools click
    click CLI1 "https://github.com/trvorth/qanto/blob/main/src/bin/qanto.rs"
    click CLI2 "https://github.com/trvorth/qanto/blob/main/src/bin/qantowallet.rs"
    click CLI3 "https://github.com/trvorth/qanto/blob/main/src/bin/saga_assistant.rs"
    click CLI4 "https://github.com/trvorth/qanto/blob/main/src/bin/monitor.rs"
    click CLI1 "https://github.com/trvorth/qanto/blob/main/src/bin/start_node.rs"
    click CLI1 "https://github.com/trvorth/qanto/blob/main/src/bin/generate_wallet.rs"
    click CLI1 "https://github.com/trvorth/qanto/blob/main/src/bin/get_address.rs"
    click CLI1 "https://github.com/trvorth/qanto/blob/main/src/bin/import_wallet.rs"
    click CLI1 "https://github.com/trvorth/qanto/blob/main/src/bin/omega_test.rs"

    %% Relayer click
    click Relayer "https://github.com/trvorth/qanto/blob/main/tools/relayer/src/main.rs"
    click Relayer "https://github.com/trvorth/qanto/blob/main/tools/relayer/Cargo.toml"

    %% Explorer & Docs click
    click Explorer "https://github.com/trvorth/qanto/blob/main/qanto-explorer.html"
    click Docs "https://github.com/trvorth/qanto/tree/main/qanto-docs/"
    click Website "https://github.com/trvorth/qanto/tree/main/website/"

    %% Deployment Infra click
    click K8s "https://github.com/trvorth/qanto/tree/main/helm/api/"
    click K8s "https://github.com/trvorth/qanto/tree/main/helm/boot-node/"
    click K8s "https://github.com/trvorth/qanto/tree/main/helm/website/"

    %% Configuration examples
    click NodeService "https://github.com/trvorth/qanto/blob/main/config.toml"
    click NodeService "https://github.com/trvorth/qanto/blob/main/.env.example"

    %% Styles
    classDef core fill:#cfe2ff,stroke:#1f4e79,color:#1f4e79
    classDef offchain fill:#d5e8d4,stroke:#38761d,color:#38761d
    classDef external fill:#fce5cd,stroke:#e69138,color:#e69138
    classDef infra fill:#e7e6f7,stroke:#674ea7,color:#674ea7
```
