# garynvu/blockchain-go architecture

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

- Interactive diagram: https://gitdiagram.com/garynvu/blockchain-go
- Repository: https://github.com/garynvu/blockchain-go

## Overview

##### Project type and purpose
- This is a standalone, full‐node blockchain implementation written in Go.
- It provides a CLI interface for mining blocks, creating and signing transactions, and querying the ledger.
- The core functionality lives in the `blockchain` package; wallet management is in `wallet`; the executable glue is in `cli` and `main.go`.

##### File structure
- Top‐level:
- `main.go` – entry point that initializes the node and dispatches CLI commands
- `cli/cli.go` – command‐line parsing and user interactions
- `blockchain/` – core chain data structures (`block.go`, `transaction.go`, etc.), proof‐of‐work (`proof.go`), chain management (`blockchain.go`)
- `wallet/` – wallet/keypair generation (`wallet.go`), persistence (`wallets.go`), and helpers (`utils.go`)
- `tmp/` – persistent storage directory for block data files and wallet datastore
- Configuration and dependency manifests: `go.mod`, `go.sum`.

##### Extract insights from the README
- Purpose: “Creation of a blockchain with Golang”

a. Main components
1. CLI Layer
- Parses user commands (createwallet, getbalance, send, mine, printchain)
2. Application Layer (main)
- Bootstraps the CLI and wires together blockchain and wallet modules
3. Blockchain Core
- Block and Transaction models
- Blockchain manager (chain of blocks, UTXO set)
- Proof‐of‐Work engine
4. Wallet Manager
- Keypair generation
- Wallet datastore
- Transaction signing
5. Persistence Layer
- Block storage (LSM‐style SSTables and value logs under `tmp/blocks/`)
- Wallet file (`tmp/wallets.data`)

b. Relationships and interactions
- CLI → calls → Application Layer
- Application Layer → invokes → Wallet Manager (for address creation/signing)
- Application Layer → invokes → Blockchain Core (for ledger queries, mining, broadcasting txs)
- Blockchain Core ↔ Persistence Layer (read/write blocks & UTXO data)
- Wallet Manager ↔ Persistence Layer (store/load wallets)

c. Architectural patterns & principles
- Layered architecture: separation between CLI, domain logic (blockchain & wallet), and storage
- Single‐node design (no networking layer yet)
- Modular Go packages for testability and separation of concerns

d. Key technologies
- Go modules (go.mod)
- File‐based storage (custom SST/VLOG files under `tmp/`)
- Standard Go crypto libraries (for hashing, signatures)
- CLI parsing (built-in flag or custom)

##### Additional detail
- For the transaction flow:
- CLI “send” command → wallet signs transaction → blockchain verifies and appends to new block.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        CLI["CLI Layer"]:::presentation
    end

    Application["Node Entry Point"]:::presentation

    %% Domain Layer
    subgraph "Domain Layer"
        subgraph "Blockchain Core"
            BlockGo["block.go"]:::domain
            TransactionGo["transaction.go / tx.go"]:::domain
            BlockchainGo["blockchain.go"]:::domain
            ProofGo["proof.go"]:::domain
        end
        subgraph "Wallet Manager"
            WalletGo["wallet.go"]:::domain
            WalletsGo["wallets.go"]:::domain
            UtilsGo["utils.go"]:::domain
        end
    end

    %% Storage Layer
    subgraph "Storage Layer"
        subgraph "Block Storage"
            Vlog["000000.vlog"]:::storage
            SST["000002.sst"]:::storage
            Manifest["MANIFEST"]:::storage
        end
        WalletDB["wallets.data"]:::storage
    end

    %% Configuration & Docs
    subgraph "Configuration"
        GoMod["go.mod"]:::config
        GoSum["go.sum"]:::config
        README["README.md"]:::config
    end

    %% Connections
    CLI -->|parses commands| Application
    Application -->|bootstraps core| BlockchainGo
    Application -->|manages wallets| WalletGo
    BlockchainGo -->|uses models| BlockGo
    BlockchainGo -->|handles txs| TransactionGo
    BlockchainGo -->|executes PoW| ProofGo
    ProofGo -->|"hash till target"| ProofGo
    BlockGo -->|read/write| Vlog
    BlockchainGo -->|persist blocks| SST
    BlockchainGo -->|update metadata| Manifest
    WalletGo -->|sign / load| WalletsGo
    WalletGo -->|utils| UtilsGo
    WalletsGo -->|persist wallets| WalletDB

    %% Click Events
    click CLI "https://github.com/garynvu/blockchain-go/blob/main/cli/cli.go"
    click Application "https://github.com/garynvu/blockchain-go/blob/main/main.go"
    click BlockGo "https://github.com/garynvu/blockchain-go/blob/main/blockchain/block.go"
    click TransactionGo "https://github.com/garynvu/blockchain-go/blob/main/blockchain/transaction.go"
    click BlockchainGo "https://github.com/garynvu/blockchain-go/blob/main/blockchain/blockchain.go"
    click ProofGo "https://github.com/garynvu/blockchain-go/blob/main/blockchain/proof.go"
    click WalletGo "https://github.com/garynvu/blockchain-go/blob/main/wallet/wallet.go"
    click WalletsGo "https://github.com/garynvu/blockchain-go/blob/main/wallet/wallets.go"
    click UtilsGo "https://github.com/garynvu/blockchain-go/blob/main/wallet/utils.go"
    click Vlog "https://github.com/garynvu/blockchain-go/blob/main/tmp/blocks/000000.vlog"
    click SST "https://github.com/garynvu/blockchain-go/blob/main/tmp/blocks/000002.sst"
    click Manifest "https://github.com/garynvu/blockchain-go/tree/main/tmp/blocks/MANIFEST"
    click WalletDB "https://github.com/garynvu/blockchain-go/blob/main/tmp/wallets.data"
    click GoMod "https://github.com/garynvu/blockchain-go/blob/main/go.mod"
    click GoSum "https://github.com/garynvu/blockchain-go/blob/main/go.sum"
    click README "https://github.com/garynvu/blockchain-go/blob/main/README.md"

    %% Styles
    classDef presentation fill:#D6EAF8,stroke:#3498DB,color:#1B4F72;
    classDef domain fill:#D5F5E3,stroke:#28B463,color:#145A32;
    classDef storage fill:#FCF3CF,stroke:#F1C40F,color:#7D6608;
    classDef config fill:#E5E8E8,stroke:#95A5A6,color:#424949;
```
