# solo-daemon/vmkub architecture

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

- Interactive diagram: https://gitdiagram.com/solo-daemon/vmkub
- Repository: https://github.com/solo-daemon/vmkub

## Overview

##### Project type and purpose
- vmkub is a decentralized VM‐orchestration system.
- It combines:
- A Rust‐based P2P overlay (DHT) for node discovery
- On‐chain smart‐contract registries for providers & clients
- A “provider” service that actually boots VMs on hosts (via OpenSSH, VM images)
- A CLI client for users to discover, connect, and pay
- A Next.js web UI for browser‐based interaction

##### File structure
 client/cli – Rust CLI binary that parses commands, calls DHT, calls smart contracts, triggers RPC for payment, and SSH‐into provisioned VMs.
 contract/… – JSON ABIs for ProviderRegistry and ClientDataRegistry on‐chain.
 dht/ – Rust crate implementing the P2P overlay: node KD‐tree, routing, protocol, attributes, key hashing.
 provider/ – Rust service that:
– sets up OpenSSH, launches VMs via host.img
– updates the on‐chain registry
– subcrate vmkub for alternative build
 site/ – Next.js + React UI, uses Web3Modal for wallet, calls smart contracts, may invoke client API.

##### README for behavioral flows
- “cli <vmkub‐provider> setup” → boots VM, SSH, on‐chain update
- “cli <vmkub> connect” → uses DHT best‐match, RPC payment, SSH
- Chain struct stores machine specs

##### Components
a. Frontend UI (site/)
b. CLI Client (client/cli)
c. P2P DHT Network (dht/)
d. Smart Contracts on Blockchain (contract/)
e. Provider Service (provider/)
f. VM Hosts & VM Images (provider/host.img)
g. External Dependencies (OpenSSH, Ethereum node, RPC endpoint)

##### Relationships & data‐flow
1) UI ↔ Web3Modal → Blockchain (read/write registry)
2) CLI Client → DHT overlay → finds provider peers
3) CLI Client → RPC payment → Smart contract (on‐chain)
4) CLI Client → SSH → VM on Provider host
5) Provider Service registers itself to DHT + Blockchain
6) Provider Service → VM orchestration (host.img, OpenSSH) → updates on‐chain

##### Architectural patterns & principles
- Microservices & Crate separation: each major role is its own Rust crate or web app.
- P2P DHT for decentralized discovery.
- On‐chain registries for immutable, auditable provider/client states.
- CLI vs. Web UI dual front ends.
- Clear separation of on‐chain (contracts) vs. off‐chain (DHT, VM orchestration).

##### Detail to capture
– Crate names (dht, client/cli, provider) as component labels
– JSON ABI files under Blockchain component
– Next.js app under Frontend container
– External dependencies: Ethereum node endpoint, OpenSSH, VM image

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User-Facing Frontends
    subgraph "User-Facing Frontends"
        UI1["Next.js Web App"]:::frontend
        UI2["Web3Modal Context"]:::frontend
        UI3["Next.js Config"]:::frontend
    end

    %% CLI Client
    subgraph "CLI Client"
        CLI_Main["main.rs"]:::frontend
        CLI_API["api.rs"]:::frontend
        CLI_CFG["config_parser.rs"]:::frontend
    end

    %% P2P DHT Network
    subgraph "P2P DHT Network"
        DHT_Lib["lib.rs"]:::p2p
        DHT_Net["network.rs"]:::p2p
        DHT_Prot["protocol.rs"]:::p2p
        DHT_Rout["routing.rs"]:::p2p
    end

    %% On-Chain Smart Contracts
    subgraph "On-Chain Smart Contracts"
        ABI_Prov["ProviderRegistryABI.json"]:::blockchain
        ABI_Client["ClientDataRegistryABI.json"]:::blockchain
    end

    %% Provider Service
    subgraph "Provider Service"
        Prov_Svc["provider.rs"]:::orch
        Prov_VM["vm.rs"]:::orch
        Host_IMG["host.img"]:::orch
        Prov_Exp["setup.exp"]:::orch
        Prov_Shell["configure.sh"]:::orch

        subgraph "vmkub Subcrate"
            VMK_Main["main.rs"]:::orch
            VMK_IMG["host.img"]:::orch
            VMK_Cargo["Cargo.toml"]:::orch
        end
    end

    %% External Dependencies
    Ethereum["Ethereum Node Endpoint"]:::external
    SSH["OpenSSH"]:::external

    %% Connections
    UI1 -->|calls JSON-RPC| ABI_Prov
    UI1 -->|calls JSON-RPC| ABI_Client
    UI1 -->|uses Web3Modal| Ethereum

    CLI_Main -->|libp2p routing| DHT_Prot
    CLI_Main -->|RPC payment| ABI_Prov
    CLI_Main -->|SSH tunnel| Host_IMG
    CLI_Main -->|discovers peers| DHT_Net

    Prov_Svc -->|updates on-chain| ABI_Prov
    Prov_Svc -->|joins DHT| DHT_Lib
    Prov_Svc -->|orchestrates VM| VMK_Main
    Prov_Svc -->|uses SSH| SSH

    Ethereum ---|provides blockchain| ABI_Prov
    SSH ---|enables access| Host_IMG

    %% Click Events
    click UI1 "https://github.com/solo-daemon/vmkub/blob/main/site/src/app/page.js"
    click UI2 "https://github.com/solo-daemon/vmkub/blob/main/site/src/context/Web3Modal.jsx"
    click UI3 "https://github.com/solo-daemon/vmkub/blob/main/site/next.config.mjs"
    click CLI_Main "https://github.com/solo-daemon/vmkub/blob/main/client/cli/src/main.rs"
    click CLI_API "https://github.com/solo-daemon/vmkub/blob/main/client/cli/src/api.rs"
    click CLI_CFG "https://github.com/solo-daemon/vmkub/blob/main/client/cli/src/config_parser.rs"
    click DHT_Lib "https://github.com/solo-daemon/vmkub/blob/main/dht/src/lib.rs"
    click DHT_Net "https://github.com/solo-daemon/vmkub/blob/main/dht/src/network.rs"
    click DHT_Prot "https://github.com/solo-daemon/vmkub/blob/main/dht/src/protocol.rs"
    click DHT_Rout "https://github.com/solo-daemon/vmkub/blob/main/dht/src/routing.rs"
    click ABI_Prov "https://github.com/solo-daemon/vmkub/blob/main/contract/provider/ProviderRegistryABI.json"
    click ABI_Client "https://github.com/solo-daemon/vmkub/blob/main/contract/client/ClientDataRegistryABI.json"
    click Prov_Svc "https://github.com/solo-daemon/vmkub/blob/main/provider/src/provider.rs"
    click Prov_VM "https://github.com/solo-daemon/vmkub/blob/main/provider/src/vm.rs"
    click Host_IMG "https://github.com/solo-daemon/vmkub/blob/main/provider/host.img"
    click Prov_Exp "https://github.com/solo-daemon/vmkub/blob/main/provider/setup.exp"
    click Prov_Shell "https://github.com/solo-daemon/vmkub/blob/main/provider/configure.sh"
    click VMK_Main "https://github.com/solo-daemon/vmkub/blob/main/provider/vmkub/src/main.rs"
    click VMK_IMG "https://github.com/solo-daemon/vmkub/blob/main/provider/vmkub/host.img"
    click VMK_Cargo "https://github.com/solo-daemon/vmkub/blob/main/provider/vmkub/Cargo.toml"

    %% Styles
    classDef frontend fill:#D8B4FE,stroke:#7C3AED,color:#111
    classDef p2p fill:#ADF7B6,stroke:#22C55E,color:#111
    classDef blockchain fill:#BFDBFE,stroke:#3B82F6,color:#111
    classDef orch fill:#FED7AA,stroke:#F97316,color:#111
    classDef external fill:#E5E7EB,stroke:#6B7280,color:#111
```
