# mjohnson518/supernova architecture

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

- Interactive diagram: https://gitdiagram.com/mjohnson518/supernova
- Repository: https://github.com/mjohnson518/supernova

## Overview

##### Project type and purpose
- Supernova is a full-stack, production-grade proof-of-work blockchain platform implemented in Rust.
- It comprises a core library (btclib), a node daemon, a mining service, a CLI wallet, and auxiliary tools (e.g., ASCII art banner, test harnesses).
- It exposes REST-RPC interfaces, P2P networking, environmental tracking, security mitigation, monitoring, and Lightning Network support.

##### File structure
- Top-level components:
- btclib/        – Core blockchain library (consensus, crypto, UTXO, storage, mempool, environmental, security, lightning, testnet harness)
- node/          – Node binary (network stack, P2P, RPC server, API routes, storage persistence, metrics, middleware)
- miner/         – Mining binary (template generation, work coordination, reward distribution, green mining registration)
- wallet/        – Wallet CLI (HD-wallet, key management, transaction creation, Lightning commands, TUI)
- supernova/     – ASCII art banner utilities
- tests/, scripts/, docker/, kubernetes/, helm/, deployments/ – CI/CD, containerization, orchestration, testnet setup
- Look for build files (Cargo.toml), configuration (config/node.toml), Dockerfiles, Helm charts.
- Notice modular namespaces under btclib (crypto/, consensus/, storage/, environmental/, lightning/) and under node (network/, api/, storage/, metrics/).

##### README for additional insights
- Architecture summary lists Core Library, Node, Miner, Wallet, Environmental System, Security System, Monitoring, Lightning.
- Key technologies: Rust, libp2p, JSON-RPC, REST, Prometheus, Grafana, Docker, Kubernetes, Helm.
- Deployment patterns: Docker Compose for testnet, Helm charts for production, scripts for backups and disaster recovery.

a. Main components:
- Clients: Wallet CLI, Admin CLI, ASCII Banner Tool
- Node Service: API Server (REST & JSON-RPC), P2P Network, Mempool Manager, Block Processor, Storage
- Core Library (btclib): Consensus Engine, Crypto Primitives, UTXO Model, Validation, Environmental Tracker, Security Modules, Lightning Core
- Miner Service: Mining Coordinator, Worker Pools, Difficulty Adjuster, Green Mining Interface
- Lightning Service: Off-chain channel manager (node + wallet integration)
- Databases & Persistence: Block store, UTXO database, Checkpoints, Backups
- Monitoring Stack: Prometheus, Grafana Dashboard
- External Services: Peers over P2P Overlay, OpenSSL, Kubernetes Cluster, Docker Registry
b. Relationships and interactions:
- Wallet → Node: sends signed transactions via REST/JSON-RPC → Node’s Mempool
- Node ↔ P2P Network: gossip transactions & blocks, peer management
- Node → btclib: invoke consensus validation, state updates, storage writes
- Miner ← Node API: fetch block template → Miner performs PoW → Miner submits new block via Node API
- Node → Storage: append blocks to block store, update UTXO set; perform backups
- Node → Monitoring: push metrics to Prometheus endpoint → Grafana fetches dashboards
- Lightning: Wallet and Node coordinate to open/close channels, watchtower integration, fees track through environmental module
- Kubernetes/Helm: orchestrate Node, Miner, Grafana, Prometheus, Backup CronJobs
c. Architectural patterns & design principles:
- Modular Library-Driven Design: btclib reused by node, miner, wallet
- Hexagonal Architecture: adapters for storage, network, API, CLI
- Layered Security: separate modules for Sybil, Eclipse, rate limiting
- Observer Pattern: metrics collectors feeding Prometheus
- Event-Driven / Asynchronous P2P and Mining tasks
- Configuration-Driven Deployment (TOML, Helm values)
d. Technologies & frameworks:
- Rust/Cargo
- libp2p (P2P transport)
- JSON-RPC / REST via Actix-Web or Warp
- Prometheus Client, Grafana
- Docker, Docker-Compose
- Kubernetes & Helm
- OpenSSL for crypto
- Post-quantum libs (Falcon, lattice-based primitives)

##### Detail & separation
- Break out sub-components only as deep as needed for clarity (e.g., show Node subdivided into API, P2P, Storage, Metrics).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% On-Chain Components
    subgraph "On-Chain Components"
        subgraph "Core Library"
            consensus["btclib::consensus"]:::core
            crypto["btclib::crypto"]:::core
            storage_core["btclib::storage"]:::core
            env["btclib::environmental"]:::core
            security["btclib::security_mitigation"]:::core
            lightning_core["btclib::lightning"]:::core
        end
        subgraph "Node Service"
            api["node::api"]:::core
            p2p["node::network"]:::core
            mempool["node::mempool"]:::core
            storage_node["node::storage"]:::core
            metrics["node::metrics"]:::core
        end
        subgraph "Miner Service"
            mining["miner::mining"]:::utility
        end
    end

    %% Off-Chain Components
    subgraph "Off-Chain Components"
        wallet_cli["wallet::cli"]:::utility
        tui["wallet::ui"]:::ui
        banner["ASCII Banner Tool"]:::utility
    end

    %% Infrastructure
    subgraph "Infrastructure"
        docker_compose["Docker Compose"]:::infra
        helm["Helm Charts"]:::infra
        kubernetes["Kubernetes Manifests"]:::infra
        cron["Backup CronJobs"]:::infra
    end

    %% External & Monitoring
    subgraph "External & Monitoring"
        p2p_network["P2P Network"]:::external
        openssl["OpenSSL"]:::external
        prometheus["Prometheus"]:::db
        grafana["Grafana"]:::db
    end

    %% Databases & Persistence
    subgraph "Databases & Persistence"
        block_store["Block Store"]:::db
        utxo_db["UTXO Database"]:::db
        checkpoints["Checkpoints"]:::db
        backups["Backups"]:::db
    end

    %% Relationships
    wallet_cli -->|"submit_transaction()"| api
    api -->|"invoke consensus"| consensus
    api -->|"get_block_template()"| mining
    p2p -->|"gossip()"| p2p_network
    mining -->|"submit_block()"| api
    api -->|"append_block()"| block_store
    block_store -->|"update UTXO"| utxo_db
    api -->|"push_metrics()"| prometheus
    prometheus -->|"fetch dashboards"| grafana
    api -->|"use crypto"| crypto
    api -->|"validate storage"| storage_core
    api -->|"track env"| env
    api -->|"mitigate threats"| security
    api -->|"manage channels"| lightning_core
    wallet_cli -->|"display UI"| tui
    docker_compose --> wallet_cli
    docker_compose --> api
    docker_compose --> mining
    docker_compose --> prometheus
    docker_compose --> grafana
    kubernetes --> api
    kubernetes --> mining
    kubernetes --> prometheus
    kubernetes --> grafana
    cron --> backups
    api -->|"persist data"| storage_node
    api -->|"collect metrics"| metrics
    api -->|"manage mempool"| mempool
    api -->|"ssl crypto"| openssl

    %% Click Events
    click consensus "https://github.com/mjohnson518/supernova/tree/main/btclib/src/consensus"
    click crypto "https://github.com/mjohnson518/supernova/tree/main/btclib/src/crypto"
    click storage_core "https://github.com/mjohnson518/supernova/tree/main/btclib/src/storage"
    click env "https://github.com/mjohnson518/supernova/tree/main/btclib/src/environmental"
    click security "https://github.com/mjohnson518/supernova/blob/main/btclib/src/security_mitigation.rs"
    click lightning_core "https://github.com/mjohnson518/supernova/tree/main/btclib/src/lightning"
    click api "https://github.com/mjohnson518/supernova/tree/main/node/src/api"
    click p2p "https://github.com/mjohnson518/supernova/tree/main/node/src/network"
    click storage_node "https://github.com/mjohnson518/supernova/tree/main/node/src/storage"
    click metrics "https://github.com/mjohnson518/supernova/tree/main/node/src/metrics"
    click mempool "https://github.com/mjohnson518/supernova/tree/main/node/src/mempool"
    click mining "https://github.com/mjohnson518/supernova/tree/main/miner/src/mining"
    click wallet_cli "https://github.com/mjohnson518/supernova/tree/main/wallet/src/"
    click tui "https://github.com/mjohnson518/supernova/tree/main/wallet/src/ui"
    click banner "https://github.com/mjohnson518/supernova/blob/main/supernova/src/main.rs"
    click docker_compose "https://github.com/mjohnson518/supernova/blob/main/docker/docker-compose.yml"
    click helm "https://github.com/mjohnson518/supernova/blob/main/helm/supernova/Chart.yaml"
    click kubernetes "https://github.com/mjohnson518/supernova/tree/main/kubernetes/helm/supernova/templates"
    click cron "https://github.com/mjohnson518/supernova/blob/main/deployments/testnet/docker-compose.yml"

    %% Styles
    classDef core fill:#cce5ff,stroke:#004085,color:#004085
    classDef utility fill:#d4edda,stroke:#155724,color:#155724
    classDef db fill:#e2e3e5,stroke:#383d41,color:#383d41
    classDef external fill:#f8d7da,stroke:#721c24,color:#721c24
    classDef infra fill:#d6d8d9,stroke:#1b1e21,color:#1b1e21
    classDef ui fill:#fff3cd,stroke:#856404,color:#856404
```
