# secblockchain/core-blockchain architecture

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

- Interactive diagram: https://gitdiagram.com/secblockchain/core-blockchain
- Repository: https://github.com/secblockchain/core-blockchain

## Overview

##### Project type and purpose
- This is a distributed blockchain node implementation (“Smart Energy Coin Validator Node”) based on Go-Ethereum.
- It provides CLI scripts for installation (`node-setup.sh`), node lifecycle (`node-start.sh`, `node-stop.sh`), and runs a customized geth‐style binary under the hood.

##### File structure
Top‐level:
- `.env`, `README.md`, `genesis.json`, `chaindata/` (on-disk chain DB)
- `node-setup.sh`, `node-start.sh`, `node-stop.sh` (shell orchestration)
- `node_src/` – Go source of a full Ethereum‐compatible node (p2p, consensus, RPC, core, crypto, etc.)
Key patterns:
- `accounts/`, `keystore/` modules handle wallet & validators
- `consensus/` implements DPoS and variants (clique, ethash)
- `p2p/`, `devp2p/` manage peer discovery & networking
- `rpc/`, `graphql/` expose JSON-RPC and GraphQL APIs
- `core/`, `state/`, `trie/`, `rlp/`, `eth/` process blocks, state transitions, VM execution
- `cmd/` contains CLI entry points (`geth`, `bootnode`, `evm`, `clef`, `puppeth`, `faucet`, etc.)

##### Extract insights from README
- This repository bundles multiple release candidates of an SEC DPoS chain.
- Installation: runs `node-setup.sh` to compile/configure a validator or RPC node.
- Usage: `node-start.sh`/`node-stop.sh` to run or halt validator/RPC instance.
- Interactive console via tmux for on-chain management (staking, monitoring).

##### Elements
- Shell scripts (oval/green)
- Node binary modules (rectangles/blue)

##### Final advice
- On-chain and off-chain interactions (staking UI, system contracts).
- Configuration files (`genesis.json`, `node.toml`) feeding into the node at startup.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Shell Orchestrator
    subgraph "Shell Orchestrator"
        Setup((node-setup.sh)):::shell
        Start((node-start.sh)):::shell
        Stop((node-stop.sh)):::shell
    end
    click Setup "https://github.com/secblockchain/core-blockchain/blob/main/./node-setup.sh"
    click Start "https://github.com/secblockchain/core-blockchain/blob/main/./node-start.sh"
    click Stop "https://github.com/secblockchain/core-blockchain/blob/main/./node-stop.sh"

    %% Node Configuration
    subgraph "Node Configuration"
        Genesis["genesis.json"]:::config
        Env[".env"]:::config
    end
    click Genesis "https://github.com/secblockchain/core-blockchain/blob/main/./genesis.json"
    click Env "https://github.com/secblockchain/core-blockchain/blob/main/./.env"

    %% Core Node Binary Modules
    subgraph "Core Node Binary"
        subgraph "P2P Network Layer"
            P2P["p2p modules"]:::binary
            Devp2p["devp2p CLI"]:::binary
        end
        click P2P "https://github.com/secblockchain/core-blockchain/tree/main/node_src/p2p/"
        click Devp2p "https://github.com/secblockchain/core-blockchain/tree/main/node_src/cmd/devp2p/"

        subgraph "Consensus Engine"
            DPoS["congress (DPoS)"]:::binary
            Clique["clique (PoA)"]:::binary
            Ethash["ethash (PoW)"]:::binary
            ConsensusCore["consensus.go"]:::binary
        end
        click DPoS "https://github.com/secblockchain/core-blockchain/tree/main/node_src/consensus/congress/"
        click Clique "https://github.com/secblockchain/core-blockchain/tree/main/node_src/consensus/clique/"
        click Ethash "https://github.com/secblockchain/core-blockchain/tree/main/node_src/consensus/ethash/"
        click ConsensusCore "https://github.com/secblockchain/core-blockchain/blob/main/node_src/consensus/consensus.go"

        TxPool["tx_pool.go"]:::binary
        click TxPool "https://github.com/secblockchain/core-blockchain/blob/main/node_src/core/tx_pool.go"

        subgraph "State Management"
            State["state modules"]:::binary
            Trie["trie modules"]:::binary
        end
        click State "https://github.com/secblockchain/core-blockchain/tree/main/node_src/core/state/"
        click Trie "https://github.com/secblockchain/core-blockchain/tree/main/node_src/trie/"

        subgraph "Block Processing & EVM"
            Blockchain["blockchain.go"]:::binary
            EVM["evm.go"]:::binary
            VM["vm modules"]:::binary
        end
        click Blockchain "https://github.com/secblockchain/core-blockchain/blob/main/node_src/core/blockchain.go"
        click EVM "https://github.com/secblockchain/core-blockchain/blob/main/node_src/core/evm.go"
        click VM "https://github.com/secblockchain/core-blockchain/tree/main/node_src/core/vm/"

        subgraph "RPC Layer"
            RPC["rpc modules"]:::binary
            GraphQL["graphql modules"]:::binary
        end
        click RPC "https://github.com/secblockchain/core-blockchain/tree/main/node_src/rpc/"
        click GraphQL "https://github.com/secblockchain/core-blockchain/tree/main/node_src/graphql/"

        Keystore["keystore"]:::binary
        click Keystore "https://github.com/secblockchain/core-blockchain/tree/main/node_src/accounts/keystore/"

        subgraph "Interactive Console"
            Bridge["bridge.go"]:::binary
            Console["console.go"]:::binary
        end
        click Bridge "https://github.com/secblockchain/core-blockchain/blob/main/node_src/console/bridge.go"
        click Console "https://github.com/secblockchain/core-blockchain/blob/main/node_src/console/console.go"

        subgraph "Metrics & Logging"
            Metrics["metrics"]:::binary
            Log["log"]:::binary
        end
        click Metrics "https://github.com/secblockchain/core-blockchain/tree/main/node_src/metrics/"
        click Log "https://github.com/secblockchain/core-blockchain/tree/main/node_src/log/"
    end

    %% Storage Layer
    Storage1[(chaindata/)]:::storage
    click Storage1 "https://github.com/secblockchain/core-blockchain/tree/main/./chaindata/"
    Storage2[(LevelDB)]:::storage
    click Storage2 "https://github.com/secblockchain/core-blockchain/tree/main/node_src/ethdb/leveldb/"

    %% External Integrations
    subgraph "External Integrations"
        UI["Staking UI / Metamask"]:::external
        Contracts["System Contracts"]:::external
    end

    %% Data Flows
    Setup -->|provision & configure| Genesis
    Setup -->|load env| Env
    Start -->|launch node| P2P
    Start -->|launch node| ConsensusCore
    Start -->|launch node| RPC
    Start -->|launch node| Blockchain

    P2P -->|"gossip blocks/txs"| TxPool
    TxPool -->|"pending txs"| State
    State -->|"world state"| Trie
    Blockchain -->|"exec blocks"| EVM
    EVM -->|"write state"| Storage1
    P2P -->|"store peers"| Storage2
    ConsensusCore -->|"propose & validate"| Blockchain
    Keystore -->|"sign blocks/txs"| ConsensusCore
    RPC -->|"query & submit"| State
    RPC -->|"broadcast txs"| P2P
    Bridge -->|"admin REPL"| State
    Metrics -->|"collect stats"| RPC
    Log -->|"record events"| Storage2
    UI -->|"JSON-RPC calls"| RPC
    Contracts -->|"load at genesis"| ConsensusCore

    %% Styles
    classDef shell fill:#a4f9a1,stroke:#333,stroke-width:1px
    classDef config fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef binary fill:#89CFF0,stroke:#333,stroke-width:1px
    classDef storage fill:#f9d785,stroke:#333,stroke-width:1px
    classDef external fill:#d3d3d3,stroke:#333,stroke-width:1px
```
