# josecantero/soverx architecture

> Architecture diagram of the GitHub repository josecantero/soverx, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/josecantero/soverx
- Repository: https://github.com/josecantero/soverx

## Overview

Soverx is a C++ proof-of-work blockchain node with a CLI wallet, P2P networking, and JSON-RPC. The main workflow starts in the CLI: initialize the chain, create and sign a transaction or mine pending transactions, validate and update the UTXO-backed chain, then persist state and broadcast blocks. Peers synchronize chains and use witness checks for suspicious blocks; RPC clients can query balances or submit transactions. The graph preserves documented security, API, and storage capabilities; several subsystem links rely on README descriptions because their implementation excerpts were not shown.

Main entry points: [`src/blockchain.cpp`](https://github.com/josecantero/soverx/blob/main/src/blockchain.cpp) (Blockchain), [`src/main.cpp`](https://github.com/josecantero/soverx/blob/main/src/main.cpp) (CLI runtime), [`src/networking/Node.cpp`](https://github.com/josecantero/soverx/blob/main/src/networking/Node.cpp) (P2P node), [`src/api/RpcServer.cpp`](https://github.com/josecantero/soverx/blob/main/src/api/RpcServer.cpp) (JSON-RPC server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Node entry"]
  node_main["CLI runtime<br/>[main.cpp]"]
end

subgraph group_ledger["Ledger and consensus"]
  node_blockchain["Blockchain<br/>[blockchain.cpp]"]
  node_block["Block validation<br/>[block.cpp]"]
  node_transaction["UTXO transactions<br/>[transaction.cpp]"]
  node_merkle["Merkle tree<br/>[merkle_tree.cpp]"]
  node_storage[("LevelDB storage")]
end

subgraph group_network["P2P network"]
  node_node["P2P node<br/>[Node.cpp]"]
  node_peer["Peer connections<br/>[Peer.cpp]"]
  node_message["Wire protocol<br/>[Message.h]"]
end

subgraph group_interfaces["Wallet and API"]
  node_wallet["Wallet<br/>[wallet.cpp]"]
  node_rpc["JSON-RPC server<br/>[RpcServer.cpp]"]
  node_apikey["API keys<br/>[ApiKeyManager.cpp]"]
  node_ratelimit["Rate limiting<br/>[RateLimiter.cpp]"]
end

subgraph group_foundation["Crypto and persistence"]
  node_crypto["ECDSA and SHA-256<br/>[crypto.cpp]"]
  node_randomx["RandomX PoW<br/>[randomx_util.cpp]"]
  node_base58["Base58 addresses<br/>[base58.cpp]"]
  node_serialization["Binary serialization"]
  node_config["Configuration<br/>[config.cpp]"]
end

node_operator(("Node operator"))
node_rpcclient(("RPC client"))
node_peers(("Network peers"))
node_leveldb[("LevelDB")]

node_operator -->|"runs"| node_main
node_main -->|"initializes"| node_blockchain
node_main -->|"creates or loads"| node_wallet
node_wallet -->|"creates and signs"| node_transaction
node_main -->|"submits transaction"| node_blockchain
node_blockchain -->|"validates UTXOs"| node_transaction
node_blockchain -->|"mines and validates"| node_block
node_block -->|"builds root"| node_merkle
node_block -->|"hashes proof"| node_randomx
node_transaction -->|"checks signatures"| node_crypto
node_wallet -->|"derives keys"| node_crypto
node_crypto -->|"encodes addresses"| node_base58
node_blockchain -->|"persists chain state"| node_storage
node_storage -->|"reads and writes"| node_leveldb
node_storage -->|"serializes records"| node_serialization
node_main -->|"starts node"| node_node
node_main -->|"starts RPC"| node_rpc
node_rpcclient -->|"sends requests"| node_rpc
node_rpc -->|"queries and submits"| node_blockchain
node_rpc -->|"authenticates keys"| node_apikey
node_rpc -->|"limits requests"| node_ratelimit
node_node -->|"syncs and submits blocks"| node_blockchain
node_node -->|"handles connections"| node_peer
node_peer -->|"exchanges messages"| node_message
node_node -->|"discovers and broadcasts"| node_peers
node_node -->|"requests witnesses"| node_blockchain
node_config -->|"configures runtime"| node_main
node_main -->|"migrates legacy data"| node_blockchain

click node_main "https://github.com/josecantero/soverx/blob/main/src/main.cpp"
click node_blockchain "https://github.com/josecantero/soverx/blob/main/src/blockchain.cpp"
click node_block "https://github.com/josecantero/soverx/blob/main/src/block.cpp"
click node_transaction "https://github.com/josecantero/soverx/blob/main/src/transaction.cpp"
click node_merkle "https://github.com/josecantero/soverx/blob/main/src/merkle_tree.cpp"
click node_storage "https://github.com/josecantero/soverx/blob/main/src/storage/storage_manager.cpp"
click node_node "https://github.com/josecantero/soverx/blob/main/src/networking/Node.cpp"
click node_peer "https://github.com/josecantero/soverx/blob/main/src/networking/Peer.cpp"
click node_message "https://github.com/josecantero/soverx/blob/main/src/networking/Message.h"
click node_wallet "https://github.com/josecantero/soverx/blob/main/src/wallet.cpp"
click node_rpc "https://github.com/josecantero/soverx/blob/main/src/api/RpcServer.cpp"
click node_apikey "https://github.com/josecantero/soverx/blob/main/src/api/ApiKeyManager.cpp"
click node_ratelimit "https://github.com/josecantero/soverx/blob/main/src/api/RateLimiter.cpp"
click node_crypto "https://github.com/josecantero/soverx/blob/main/src/crypto.cpp"
click node_randomx "https://github.com/josecantero/soverx/blob/main/src/randomx_util.cpp"
click node_base58 "https://github.com/josecantero/soverx/blob/main/src/base58.cpp"
click node_serialization "https://github.com/josecantero/soverx/blob/main/src/persistence_util.cpp"
click node_config "https://github.com/josecantero/soverx/blob/main/src/config.cpp"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_rpcclient toneBlue
class node_blockchain,node_block,node_transaction,node_merkle,node_storage,node_leveldb toneAmber
class node_node,node_peer,node_message toneMint
class node_wallet,node_rpc,node_apikey,node_ratelimit toneRose
class node_crypto,node_randomx,node_base58,node_serialization,node_config,node_operator,node_peers toneIndigo
```

## Components

### Node entry

- [CLI runtime](https://github.com/josecantero/soverx/blob/main/src/main.cpp): `src/main.cpp`

### Ledger and consensus

- [Blockchain](https://github.com/josecantero/soverx/blob/main/src/blockchain.cpp): `src/blockchain.cpp`
- [Block validation](https://github.com/josecantero/soverx/blob/main/src/block.cpp): `src/block.cpp`
- [UTXO transactions](https://github.com/josecantero/soverx/blob/main/src/transaction.cpp): `src/transaction.cpp`
- [Merkle tree](https://github.com/josecantero/soverx/blob/main/src/merkle_tree.cpp): `src/merkle_tree.cpp`
- [LevelDB storage](https://github.com/josecantero/soverx/blob/main/src/storage/storage_manager.cpp): `src/storage/storage_manager.cpp`

### P2P network

- [P2P node](https://github.com/josecantero/soverx/blob/main/src/networking/Node.cpp): `src/networking/Node.cpp`
- [Peer connections](https://github.com/josecantero/soverx/blob/main/src/networking/Peer.cpp): `src/networking/Peer.cpp`
- [Wire protocol](https://github.com/josecantero/soverx/blob/main/src/networking/Message.h): `src/networking/Message.h`

### Wallet and API

- [Wallet](https://github.com/josecantero/soverx/blob/main/src/wallet.cpp): `src/wallet.cpp`
- [JSON-RPC server](https://github.com/josecantero/soverx/blob/main/src/api/RpcServer.cpp): `src/api/RpcServer.cpp`
- [API keys](https://github.com/josecantero/soverx/blob/main/src/api/ApiKeyManager.cpp): `src/api/ApiKeyManager.cpp`
- [Rate limiting](https://github.com/josecantero/soverx/blob/main/src/api/RateLimiter.cpp): `src/api/RateLimiter.cpp`

### Crypto and persistence

- [ECDSA and SHA-256](https://github.com/josecantero/soverx/blob/main/src/crypto.cpp): `src/crypto.cpp`
- [RandomX PoW](https://github.com/josecantero/soverx/blob/main/src/randomx_util.cpp): `src/randomx_util.cpp`
- [Base58 addresses](https://github.com/josecantero/soverx/blob/main/src/base58.cpp): `src/base58.cpp`
- [Binary serialization](https://github.com/josecantero/soverx/blob/main/src/persistence_util.cpp): `src/persistence_util.cpp`
- [Configuration](https://github.com/josecantero/soverx/blob/main/src/config.cpp): `src/config.cpp`

### Other components

- **Node operator**
- **RPC client**
- **Network peers**
- **LevelDB**

## Connections

- Node operator → CLI runtime: runs (evidence: `src/main.cpp`)
- CLI runtime → Blockchain: initializes (evidence: `src/main.cpp`)
- CLI runtime → Wallet: creates or loads (evidence: `src/main.cpp`)
- Wallet → UTXO transactions: creates and signs (evidence: `README.md`)
- CLI runtime → Blockchain: submits transaction (evidence: `src/main.cpp`)
- Blockchain → UTXO transactions: validates UTXOs (evidence: `README.md`)
- Blockchain → Block validation: mines and validates (evidence: `README.md`)
- Block validation → Merkle tree: builds root (evidence: `README.md`)
- Block validation → RandomX PoW: hashes proof (evidence: `src/block.cpp`)
- UTXO transactions → ECDSA and SHA-256: checks signatures (evidence: `src/transaction.cpp`)
- Wallet → ECDSA and SHA-256: derives keys (evidence: `README.md`)
- ECDSA and SHA-256 → Base58 addresses: encodes addresses (evidence: `src/crypto.cpp`)
- Blockchain → LevelDB storage: persists chain state (evidence: `README.md`)
- LevelDB storage → LevelDB: reads and writes (evidence: `README.md`)
- LevelDB storage → Binary serialization: serializes records (evidence: `src/storage/storage_manager.cpp`)
- CLI runtime → P2P node: starts node (evidence: `src/main.cpp`)
- CLI runtime → JSON-RPC server: starts RPC (evidence: `src/main.cpp`)
- RPC client → JSON-RPC server: sends requests (evidence: `README.md`)
- JSON-RPC server → Blockchain: queries and submits (evidence: `src/api/RpcServer.cpp`)
- JSON-RPC server → API keys: authenticates keys (evidence: `src/api/RpcServer.cpp`)
- JSON-RPC server → Rate limiting: limits requests
- P2P node → Blockchain: syncs and submits blocks (evidence: `README.md`)
- P2P node → Peer connections: handles connections (evidence: `src/networking/Node.cpp`)
- Peer connections → Wire protocol: exchanges messages (evidence: `src/networking/Peer.cpp`)
- P2P node → Network peers: discovers and broadcasts (evidence: `README.md`)
- P2P node → Blockchain: requests witnesses (evidence: `README.md`)
- Configuration → CLI runtime: configures runtime (evidence: `src/main.cpp`)
- CLI runtime → Blockchain: migrates legacy data (evidence: `src/main.cpp`)
