# nibiruchain/nibiru architecture

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

- Interactive diagram: https://gitdiagram.com/nibiruchain/nibiru
- Repository: https://github.com/nibiruchain/nibiru

## Overview

##### Main Components
- Consensus Layer – Tendermint Core: Highlight Tendermint as the underlying consensus engine. This layer is responsible for the blockchain’s distributed consensus and network communication.
– EVM Module: Supporting Ethereum Virtual Machine operations. Include components such as the EVM state database, JSON-RPC endpoints (found in eth/rpc and related directories), and precompiled contracts (from the evm/precompile folder).
– WASM Module: Governing CosmWasm smart contract execution (the “wasmext” package and associated client interfaces).
– Devgas Module: For sharing contract execution fees with smart contract developers.
– Epochs, Inflation, Oracle, and Other 'x' Modules: From the “x” directory including modules such as epochs, inflation, oracle, tokenfactory, and common utilities.
– Other Core Components: Things like upgrade management, genesis configuration (from folders like app/upgrades and proto directories) and keepers that manage state (as seen in app/keepers and similar folders).
- RPC/API Gateway: This layer exposes both Cosmos-SDK JSON-RPC and Ethereum-compatible JSON-RPC endpoints. This becomes the bridge between external clients and the core.
- CLI & Node Management: Mark the “nibid” CLI inside the cmd folder as an entry point for operators and developers (with connections to underlying modules and configuration files).

##### Relationships and Data Flow
- Data flows from the API Gateway to the Nibiru Chain Application.
- Inside the application, indicate module interactions: for instance, the EVM module’s dependency on the common module for shared utilities, or the interdependencies between modules (like oracle updating asset prices which might affect inflation control).
- How the consensus engine (Tendermint Core) feeds finalized blocks to the application and how state transitions are managed via the keepers.

##### Architectural Patterns and Design Principles
- Layered Architecture: Clearly separate the networking/consensus layer (Tendermint) from the business logic (Cosmos-SDK application modules) and the external API interfaces.

##### Relevant Technologies and Tools
- Technologies: Golang for the core, Docker for containerization (referenced by Dockerfile, docker-compose, etc.), protobufs (in the proto folder) for message encoding, and testing frameworks integrated via Makefiles and CI/CD workflows (observed in the .github/workflows/ directories).
- Frameworks & Libraries: Cosmos-SDK, Tendermint, and Ethereum’s geth libraries (in the eth directory) for EVM support.

##### Additional Suggestions
- Technology choices: Add labels like “Golang”, “Docker”, “Protobuf”, “Cosmos-SDK”, “Tendermint”, “JSON-RPC”, etc., to clarify the technologies used at each layer.

Happy diagramming!

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "External Interfaces"
        extClients("External Clients (CLI, SDK, RPC)"):::external
        cliManager("CLI/Node Management"):::external
        externalTools("External Tools & SDKs"):::external
        extClients --> cliManager
        extClients --> externalTools
    end

    subgraph "RPC/API Layer"
        rpc("RPC/API Gateway"):::api
    end

    subgraph "Application Layer"
        appCore("Nibiru Chain Application"):::app
        subgraph "Application Modules"
            EVM("EVM Module"):::module
            WASM("WASM Module"):::module
            Devgas("Devgas Module"):::module
            Epochs("Epochs Module"):::module
            Inflation("Inflation Module"):::module
            Oracle("Oracle Module"):::module
            Tokenfactory("Tokenfactory Module"):::module
            Upgrades("Genesis/Upgrades/Keepers"):::module
        end
    end

    subgraph "Consensus Layer"
        consensus("Tendermint Core"):::consensus
    end

    %% Connections
    extClients -->|"sends-request"| cliManager
    cliManager -->|"invokes"| rpc
    externalTools -->|"utilizes"| rpc
    rpc -->|"routes-to"| appCore
    appCore -->|"manages"| EVM
    appCore --> WASM
    appCore --> Devgas
    appCore --> Epochs
    appCore --> Inflation
    appCore --> Oracle
    appCore --> Tokenfactory
    appCore --> Upgrades
    consensus -->|"finalizes"| appCore
    Oracle -->|"affects"| Inflation

    %% Click Events
    click consensus "https://github.com/nibiruchain/nibiru/blob/main/app/appconst/consensus_config.go"
    click appCore "https://github.com/nibiruchain/nibiru/blob/main/app/app.go"
    click Upgrades "https://github.com/nibiruchain/nibiru/blob/main/app/genesis.go"
    click EVM "https://github.com/nibiruchain/nibiru/tree/main/app/evmante/"
    click WASM "https://github.com/nibiruchain/nibiru/tree/main/app/wasmext/"
    click Devgas "https://github.com/nibiruchain/nibiru/tree/main/x/devgas/"
    click Epochs "https://github.com/nibiruchain/nibiru/tree/main/x/epochs/"
    click Inflation "https://github.com/nibiruchain/nibiru/tree/main/x/inflation/"
    click Oracle "https://github.com/nibiruchain/nibiru/tree/main/x/oracle/"
    click Tokenfactory "https://github.com/nibiruchain/nibiru/tree/main/x/tokenfactory/"
    click rpc "https://github.com/nibiruchain/nibiru/blob/main/app/server/json_rpc.go"
    click cliManager "https://github.com/nibiruchain/nibiru/tree/main/cmd/nibid/"
    click externalTools "https://github.com/nibiruchain/nibiru/tree/main/Makefile"

    %% Styles
    classDef external fill:#f9d5e5,stroke:#990033,stroke-width:2px;
    classDef api fill:#cfe2f3,stroke:#084298,stroke-width:2px;
    classDef app fill:#d9ead3,stroke:#274e13,stroke-width:2px;
    classDef module fill:#fff2cc,stroke:#bf9000,stroke-width:2px;
    classDef consensus fill:#d0e0e3,stroke:#2f4f4f,stroke-width:2px;
```
