# siyovush-hamidov/pow-blockchain architecture

> Architecture diagram of the GitHub repository siyovush-hamidov/pow-blockchain, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/siyovush-hamidov/pow-blockchain
- Repository: https://github.com/siyovush-hamidov/pow-blockchain

## Overview

##### Project type and purpose
- This is a Go-based Proof-of-Work blockchain implementation (“Node” binary) plus a CLI “Client” binary.
- It demonstrates basic blockchain fundamentals: mining, block validation, P2P gossip, and simple client-node interactions.

##### File structure
- Top-level “node” entry points:
- node.go, network.go, bc.go – together build the `node` executable.
- Top-level “client” entry points:
- mainClient.go, client.go – together build the `client` executable.
- Core packages:
- /blockchain – block data structures, PoW algorithm, chain state, transaction handling, persistence to `<chain>.db`.
- /network – P2P networking, peer discovery (addrlist.json), block/tx broadcast, simple RPC or HTTP endpoints.
- Support files:
- addrlist.json – initial peer addresses.
- Makefile – builds `node` and `client`.
- LICENSE, .gitignore, go.mod/go.sum – metadata.

##### Extract insights from the README
- Two runtime roles: “node” peers that mine and gossip, and a “client” that issues commands.
- Nodes communicate over ports (e.g., 8080, 9090), load `addrlist.json`, maintain local DB (chain1.db, chain2.db).
- Client connects to a node’s address using a key file and issues commands (balance, tx, print, etc.).

a. Node Application (container)
- Sub-components:
- Network Module (from /network) – handles P2P RPC, block/tx broadcast, peer management.
- Blockchain Module (from /blockchain and bc.go) – PoW mining, block validation, chain state.
- Local Storage – persistent chain DB (e.g., chain1.db).
- Config Loader – reads addrlist.json and user key.
b. Client Application (container)
- CLI Module – user input parser (client.go)
- Network Stub – makes RPC calls to Node.
c. External Entities
- Other Node Instances – peer nodes with the same internal structure.
- addrlist.json – initial peer list.
- User’s key files – credentials for signing transactions.

##### Relationships & interactions
- Client → Node.Network API: send user commands (balance query, submit transaction).
- Node.Network → Node.Blockchain: on transaction or block receipt, forward to blockchain module.
- Node.Blockchain → Local Storage: read/write blocks.
- Node.Network ↔ Peer Node.Network: gossip new blocks/transactions.
- Node.Config Loader → Network Module: seed peers from addrlist.json.

##### Architectural patterns & principles
- Separation of Concerns:
- Transport (network) vs Domain Logic (blockchain).
- CLI (client) vs Service (node).
- P2P Gossip Pattern: nodes form a mesh, broadcast messages.
- Modular packaging: two Go modules for core functionality, two main packages for binaries.

##### Relevant technologies & frameworks
- Language: Go (modules via go.mod).
- Persistence: simple file-based DB (`<chain>.db` files).
- Build: Makefile targets `make build` → compiles `node` and `client`.
- Configuration: JSON peer list (addrlist.json), CLI flags for ports & file paths.

##### Final checklist
- [ ] All major components (Client, Node.Network, Node.Blockchain, Storage) clearly labeled
- [ ] Multiple Node instances to indicate P2P topology
- [ ] Notation for config files and key files as external artifacts

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Application
    subgraph "Client Application"
        direction TB
        Main["Client Binary"]:::cli
        CLI["CLI Module"]:::cli
        Stub["Network Stub"]:::transport
    end

    %% Node Instances
    subgraph "Node Instance 1"
        direction TB
        subgraph "Node Application"
            direction TB
            Net1["Network Module"]:::transport
            BC1["Blockchain Module"]:::domain
            Storage1["Chain DB"]:::storage
            Config1["Config Loader"]:::config
        end
    end

    subgraph "Node Instance 2"
        direction TB
        subgraph "Node Application"
            direction TB
            Net2["Network Module"]:::transport
            BC2["Blockchain Module"]:::domain
            Storage2["Chain DB"]:::storage
            Config2["Config Loader"]:::config
        end
    end

    %% External Artifacts
    Addr["addrlist.json"]:::config
    Key["User Key Files"]:::config

    %% Relationships
    Main -->|"invokes"| CLI
    CLI -->|"RPC: SubmitTx, QueryBalance"| Net1
    Net1 -->|"forward tx/block"| BC1
    BC1 -->|"read/write"| Storage1
    Config1 -->|"seed peers"| Net1
    Net1 -.->|"gossip BroadcastBlock"| Net2
    Net2 -.->|"gossip BroadcastBlock"| Net1
    Addr -->|"loaded by"| Config1
    Addr -->|"loaded by"| Config2
    Key -->|"used by"| CLI

    %% Click Events
    click Main "https://github.com/siyovush-hamidov/pow-blockchain/blob/main/mainClient.go"
    click CLI "https://github.com/siyovush-hamidov/pow-blockchain/blob/main/client.go"
    click Stub "https://github.com/siyovush-hamidov/pow-blockchain/blob/main/client.go"
    click Net1 "https://github.com/siyovush-hamidov/pow-blockchain/blob/main/network.go"
    click Net1 "https://github.com/siyovush-hamidov/pow-blockchain/blob/main/network/network.go"
    click Net2 "https://github.com/siyovush-hamidov/pow-blockchain/blob/main/network.go"
    click Net2 "https://github.com/siyovush-hamidov/pow-blockchain/blob/main/network/network.go"
    click BC1 "https://github.com/siyovush-hamidov/pow-blockchain/blob/main/bc.go"
    click BC1 "https://github.com/siyovush-hamidov/pow-blockchain/blob/main/blockchain/blockchain.go"
    click BC2 "https://github.com/siyovush-hamidov/pow-blockchain/blob/main/bc.go"
    click BC2 "https://github.com/siyovush-hamidov/pow-blockchain/blob/main/blockchain/blockchain.go"
    click Config1 "https://github.com/siyovush-hamidov/pow-blockchain/blob/main/addrlist.json"
    click Config2 "https://github.com/siyovush-hamidov/pow-blockchain/blob/main/addrlist.json"
    click Storage1 "https://github.com/siyovush-hamidov/pow-blockchain/blob/main/blockchain/blockchain.go"
    click Storage2 "https://github.com/siyovush-hamidov/pow-blockchain/blob/main/blockchain/blockchain.go"
    click Main "https://github.com/siyovush-hamidov/pow-blockchain/blob/main/mainClient.go"
    click CLI "https://github.com/siyovush-hamidov/pow-blockchain/blob/main/client.go"

    %% Styles
    classDef domain fill:#D0E8FF,stroke:#0366D6,stroke-width:2px
    classDef transport fill:#DFFFE0,stroke:#228B22,stroke-width:2px
    classDef storage fill:#FFE4B5,stroke:#FF8C00,stroke-width:2px
    classDef config fill:#F0F0F0,stroke:#666666,stroke-dasharray: 2 2
    classDef cli fill:#E8D0FF,stroke:#800080,stroke-width:2px
```
