# ignaciocorball/go-blockchain architecture

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

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

## Overview

##### Project Type and Purpose
- This is a backend-focused blockchain application written in Go.
- Purpose: expose a RESTful API for creating transactions, querying blocks, deploying/executing smart contracts, all backed by a PoS blockchain core and a BadgerDB storage layer.

##### File Structure
- Top‐level modules:
- api/        → HTTP server (Echo framework)
- blockchain/ → Core blockchain logic (blocks, transactions, PoS consensus, wallet)
- contracts/  → Smart contract framework (deployment, execution, state)
- storage/    → Persistence layer (BadgerDB integration)
- main.go     → Application entrypoint, ties everything together
- Config/build files: go.mod/go.sum
- Supporting artifacts: Postman collection for API testing

##### Key README Insights
- Stacks: Go 1.16+, Echo, BadgerDB
- Features: PoS consensus, smart contracts, ECDSA signing, REST endpoints
- Roadmap hints at P2P network layer (not yet implemented)

##### Main Architectural Components
a. Client Applications (e.g., Postman, front-end dApp)
b. API Server (Echo)
c. Blockchain Core
d. Smart Contract Engine
e. Storage Layer (BadgerDB)
f. Cryptographic Wallet Module

##### Interactions and Data Flows
1) Client → API Server: HTTP calls (/transaction, /block, /contract)
2) API Server → Blockchain Core:
- Transaction creation → Core validates & signs via wallet
- Block querying → Core retrieves from storage
- Contract deployment/execution → Delegates to Contracts module
3) Blockchain Core ↔ Storage Layer:
- Persist/Retrieve blocks, transactions, UTXOs, contract state
4) Blockchain Core → Consensus module: decides new block producer (PoS)
5) Contracts module → Storage: store contract code and state

##### Architectural Patterns & Principles
- Layered architecture: API layer, service/domain layer (blockchain + contracts), persistence layer
- Single‐binary monolith with well‐separated Go packages
- Dependency injection via Go interfaces if desired (e.g., for storage, consensus)
- Modular separation: each directory = self‐contained component

##### Final Advice
- Be very detailed: capture each major package as a component.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Clients
    subgraph "External Clients"
        direction TB
        ClientApp["Client Application (dApp)"]:::external
        Postman["Postman Collection"]:::external
    end

    %% API Layer
    subgraph "API Layer"
        direction TB
        APIServer["API Server (Echo)"]:::api
    end

    %% Core Services
    subgraph "Blockchain Core Services"
        direction TB
        Core["Blockchain Core"]:::core
        subgraph "Core Sub-Components"
            direction TB
            Consensus["PoS Consensus Module"]:::core
            UTXO["UTXO Management"]:::core
            BlockModel["Block Data Model"]:::core
            TxModel["Transaction Data Model"]:::core
            Wallet["Cryptographic Wallet Module"]:::core
        end
    end

    %% Contract Engine
    subgraph "Smart Contract Engine"
        direction TB
        Contracts["Smart Contract Engine"]:::contract
    end

    %% Storage Layer
    subgraph "Storage Layer"
        direction TB
        Storage["BadgerDB Storage"]:::storage
    end

    %% Application Entrypoint
    Main["Application Entrypoint\nmain.go"]:::core

    %% Connections
    ClientApp -->|HTTP Requests| APIServer
    Postman -->|API Tests| APIServer
    APIServer -->|CreateTransaction| Core
    APIServer -->|GetBlock| Core
    APIServer -->|DeployContract| Core

    Core -->|InvokeConsensus| Consensus
    Core -->|ManageUTXO| UTXO
    Core -->|Load/SaveBlock| BlockModel
    Core -->|Load/SaveTx| TxModel
    Core -->|SignTransaction| Wallet

    Core -->|ExecuteContract| Contracts
    Contracts -->|PersistContractState| Storage

    Core -->|Persist/Retrieve Data| Storage

    Main -->|Init API Server| APIServer
    Main -->|Init Core| Core
    Main -->|Init Contracts| Contracts
    Main -->|Init Storage| Storage

    %% Click Events
    click APIServer "https://github.com/ignaciocorball/go-blockchain/blob/main/api/server.go"
    click Core "https://github.com/ignaciocorball/go-blockchain/blob/main/blockchain/blockchain.go"
    click BlockModel "https://github.com/ignaciocorball/go-blockchain/blob/main/blockchain/block.go"
    click TxModel "https://github.com/ignaciocorball/go-blockchain/blob/main/blockchain/transaction.go"
    click Consensus "https://github.com/ignaciocorball/go-blockchain/blob/main/blockchain/consensus.go"
    click UTXO "https://github.com/ignaciocorball/go-blockchain/blob/main/blockchain/utxo.go"
    click Wallet "https://github.com/ignaciocorball/go-blockchain/blob/main/blockchain/wallet.go"
    click Contracts "https://github.com/ignaciocorball/go-blockchain/blob/main/contracts/smart_contract.go"
    click Storage "https://github.com/ignaciocorball/go-blockchain/blob/main/storage/badger.go"
    click Main "https://github.com/ignaciocorball/go-blockchain/blob/main/main.go"
    click Postman "https://github.com/ignaciocorball/go-blockchain/blob/main/blockchain.postman_collection.json"

    %% Styles
    classDef external fill:#e0f7e9,stroke:#2ecc71,color:#2c3e50;
    classDef api fill:#e8f4fc,stroke:#3498db,color:#2c3e50;
    classDef core fill:#fdf2e9,stroke:#e67e22,color:#2c3e50;
    classDef contract fill:#f5e6fc,stroke:#9b59b6,color:#2c3e50;
    classDef storage fill:#f9e7e1,stroke:#a0522d,color:#2c3e50;
```
