# tko22/simple-blockchain architecture

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

- Interactive diagram: https://gitdiagram.com/tko22/simple-blockchain
- Repository: https://github.com/tko22/simple-blockchain

## Overview

##### Project Overview
- This is a C++ blockchain implementation that mimics some design principles from Bitcoin. It supports core functions such as block creation, chain validation, and “mining” (finding a hash with a certain prefix). It also incorporates a very simple peer-to-peer network via HTTP (rather than WebSockets) for chain propagation between nodes.
- Key technologies include C++14, OpenSSL (for cryptographic operations), Simple-Web-Server (for HTTP communication), and a JSON library for data handling.

##### Main Components
- Block Data Model:
- Block.hpp: Defines the Block object that encapsulates immutable properties (index, prevHash, blockHash, nonce, and block data).
- BlockChain.hpp: Manages a vector of Blocks (using smart pointers), initializes the genesis block, and enforces chain integrity.
- Cryptographic and Utility Modules:
- crypto.hpp and hash.hpp: Provide hashing, likely using SHA-256 from OpenSSL, and related cryptographic operations.
- common.hpp and utility.hpp: Contain shared helper functions, perhaps for things like calculating Merkle roots.
- json.hh: Likely responsibilities for JSON serialization/deserialization (even if it’s from an external repository) to support HTTP payloads.
- Mining Functionality:
- findHash() function (declared in one of the headers like crypto.hpp or within the BlockChain scope) implements the “mining” process by finding a valid hash (with “00” prefix) and its accompanying nonce.
- Networking Modules:
- client_http.hpp and server_http.hpp: Provide HTTP client and server functionality, respectively, enabling the peer-to-peer network. These components allow nodes to:
- Maintain a list of other network nodes.
- Retrieve and broadcast the latest blockchain in case of updates.
- Resolve chain conflicts by electing the longest valid chain.
- Entry Point / CLI:
- main.cpp initializes the system, provides a command-line interface (CLI) to view blockchains at various indices, add new blocks, and control the mining process.
- Testing and Auxiliary Tools:
- test.sh: Script for running tests.
- js_client_test.html: Simple HTML client for interacting with the blockchain (probably to simulate HTTP interactions).
- Makefile: To build the project.

##### Relationships and Interactions
- The CLI (main.cpp) is the user’s entry point, which calls into the Blockchain object to add blocks or inspect the chain.
- The Blockchain module coordinates block validation by:
- Invoking methods from Block.hpp to create immutable blocks.
- Utilizing crypto functions (from crypto.hpp and hash.hpp) to compute hashes and verify them.
- The mining process (findHash) is triggered during block addition to ensure that the hash meets the required "proof" of work constraint (“00” prefix).
- The Networking components (via server_http.hpp and client_http.hpp) connect various nodes on different ports on the same machine (or across machines if extended) by sending HTTP requests:
- When a new block is added, the updated chain gets broadcast.
- On startup or on receiving a broadcast, nodes exchange chain data to resolve conflicts.
- Utility functions (common.hpp, utility.hpp) and JSON-related functions support data formatting and communication across components.

##### Architectural Patterns and Design Principles
- Separation of concerns is evident:
- Block and Blockchain handling vs. Cryptography vs. Networking.
- In-memory storage: All data stays in memory, which may be highlighted to show ephemeral state.
- Peer-to-peer interaction: Illustrate bi-directional or broadcast-style communication.
- Modular design: Each header (Block.hpp, crypto.hpp, etc.) represents a well-defined module with clear responsibility.
- Use of smart pointers (as seen in the Blockchain’s vector) ensures safe memory management.

##### Technical Elements
- Clear Labels: For each component such as “CLI / main.cpp”, “Blockchain Manager”, “Block Entity”, “Cryptography Module”, “Mining Functionality”, “HTTP Server”, “HTTP Client”, and “Utility Services”.
- User → CLI → Blockchain Manager.
- Blockchain Manager → Block (creation/validation).
- Blockchain Manager ↔ Cryptography Module (for hashing and Merkle root computation).
- Blockchain Manager → HTTP Server & Client (for broadcasting and receiving chain updates).
- Annotations: Add notes about design choices:
- “In-memory storage – no persistent database.”
- “HTTP requests used for node interaction instead of WebSockets.”
- “Blockchain integrity via proof-of-work style mining (with simplified ‘00’ requirement).”

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Components
    A["CLI (main.cpp)"]:::cli
    B["Blockchain Manager"]:::manager
    C["Block Entity"]:::data
    
    subgraph "Crypto Modules"
        D["crypto"]:::module
        E["hash"]:::module
    end
    
    F["Mining Functionality"]:::mining
    G["Utility Services"]:::utility
    H["JSON Handling"]:::json

    %% Networking Modules
    subgraph "Networking Modules"
        I["HTTP Server"]:::network
        J["HTTP Client"]:::network
    end

    %% Auxiliary Testing Tools
    K["Testing Tools"]:::testing

    %% Relationships
    A -->|"calls"| B
    B -->|"creates/validates"| C
    B -->|"hashes"| D
    B -->|"hashes"| E
    B -->|"triggers"| F
    B -->|"utilizes"| G
    B -->|"formats"| H
    B -->|"broadcasts to"| I
    B -->|"sends updates to"| J

    %% Click Events for Core Components
    click A "https://github.com/tko22/simple-blockchain/blob/master/main.cpp"
    click B "https://github.com/tko22/simple-blockchain/blob/master/BlockChain.hpp"
    click C "https://github.com/tko22/simple-blockchain/blob/master/Block.hpp"
    click D "https://github.com/tko22/simple-blockchain/blob/master/crypto.hpp"
    click E "https://github.com/tko22/simple-blockchain/blob/master/hash.hpp"
    click G "https://github.com/tko22/simple-blockchain/blob/master/common.hpp"
    click G "https://github.com/tko22/simple-blockchain/blob/master/utility.hpp"
    click H "https://github.com/tko22/simple-blockchain/blob/master/json.hh"
    click F "https://github.com/tko22/simple-blockchain/blob/master/BlockChain.hpp"

    %% Click Events for Networking Modules
    click I "https://github.com/tko22/simple-blockchain/blob/master/server_http.hpp"
    click J "https://github.com/tko22/simple-blockchain/blob/master/client_http.hpp"

    %% Click Events for Testing Tools
    click K "https://github.com/tko22/simple-blockchain/blob/master/test.sh"
    click K "https://github.com/tko22/simple-blockchain/blob/master/js_client_test.html"

    %% Styles
    classDef cli fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef manager fill:#87CEEB,stroke:#333,stroke-width:2px;
    classDef data fill:#98FB98,stroke:#333,stroke-width:2px;
    classDef module fill:#FFB6C1,stroke:#333,stroke-width:2px;
    classDef mining fill:#DDA0DD,stroke:#333,stroke-width:2px;
    classDef utility fill:#20B2AA,stroke:#333,stroke-width:2px;
    classDef json fill:#F4A460,stroke:#333,stroke-width:2px;
    classDef network fill:#FF6347,stroke:#333,stroke-width:2px;
    classDef testing fill:#90EE90,stroke:#333,stroke-width:2px;
```
