# neutron-org/neutron architecture

> Architecture diagram of the GitHub repository neutron-org/neutron, 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/neutron-org/neutron
- Repository: https://github.com/neutron-org/neutron

## Overview

##### Main Components
- Node Daemon & Application: Start with the cmd/neutrond directory as the execution entry-point for the blockchain node. This node bootstraps the whole application (found in the app directory) that initializes configuration, genesis state, and core runtime logic.
- Core Blockchain Modules: Under the “x” directory, various independent modules (e.g., contractmanager, cron, dex, dynamicfees, feeburner, globalfee, harpoon, ibc components, tokenfactory, transfer, etc.) implement domain-specific state transitions and business logic. These form the heart of the blockchain’s functionality.
- Protocol Definitions: The “proto” directory (and third_party/proto) houses all protobuf and swagger definitions. These represent the communication interfaces (gRPC, REST endpoints) between components as well as with external services (like IBC).
- Smart Contracts: The “contracts” and “contracts_thirdparty” directories contain WASM binaries for smart contracts deployed on-chain.
- IBC and External Communication: Modules like ibc-hooks, ibc-rate-limit, and interchainqueries as well as the networking scripts in the network folder enable inter-blockchain communication.
- Infrastructure & DevOps: Don’t forget the configuration resources like Dockerfiles, Makefile, GitHub workflows (.github/workflows/*), and the network scripts that help initialize and run local or state-synced networks.

##### Relationships & Interactions
- Data Flow starts at the node – the entry point from cmd/neutrond loads the application from the app package that sets up the state store and module routing.
- The “x” modules each encapsulate specific functionality (for example, dex for decentralized exchanges, tokenfactory for token creation, cron for scheduling tasks, etc.); they communicate with each other through well-defined interfaces, commonly using protobuf messages as defined in the proto directory.
- Smart contracts (in WASM) are loaded and executed by a specific module (likely handled or bridged by the contract manager in “x/contractmanager” or those in wasmbinding) that interacts with the blockchain’s state.
- IBC-related modules handle communication outside of the chain, connecting with other chains via IBC protocols (supported by well-structured proto definitions and additional middleware in the ibc-hooks/ and ibc-rate-limit/ directories).
- Testing components (tests, testutil, and contrib/devtools) interface with almost every part of the system for integration and system testing, ensuring all modules behave as expected.

##### Architectural Patterns & Design Principles
- Modular Architecture: The clear separation of business logic into “x” modules allows each component (e.g., dex, cron, contractmanager) to evolve independently.
- Interface-driven Communication: Extensive use of protobuf for defining gRPC/REST interfaces ensures clear and decoupled interactions.
- Interoperability via IBC: The design anticipates cross-chain communication by including dedicated IBC modules.
- Separation of Concerns: Infrastructure (network scripts, Dockerfiles, workflows) is kept separate from core blockchain logic (app, x modules) and smart contract binaries (contracts).

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% Blockchain Node & App
    subgraph "Blockchain Node & App"
        A["Neutrond Node (cmd/neutrond)"]:::runtime
        B["Application Layer (app)"]:::app
        A -->|"bootstraps"| B
    end

    %% Core Blockchain Modules
    subgraph "Core Blockchain Modules"
        CM["Contract Manager (x/contractmanager)"]:::module
        CR["Cron (x/cron)"]:::module
        DX["DEX (x/dex)"]:::module
        DF["Dynamic Fees (x/dynamicfees)"]:::module
        FB["Fee Burner (x/feeburner)"]:::module
        GF["Global Fee (x/globalfee)"]:::module
        HP["Harpoon (x/harpoon)"]:::module
        TF["Token Factory (x/tokenfactory)"]:::module
        TR["Transfer (x/transfer)"]:::module
    end

    %% Smart Contracts
    subgraph "Smart Contracts"
        SC["Contracts (contracts)"]:::contracts
        ST["Third-Party Contracts (contracts_thirdparty)"]:::contracts
    end

    %% IBC & External Communication
    subgraph "IBC & External Communication"
        IBCH["IBC Hooks (x/ibc-hooks)"]:::ibc
        IBCR["IBC Rate Limit (x/ibc-rate-limit)"]:::ibc
        ICQ["Interchain Queries (x/interchainqueries)"]:::ibc
        ICTX["Interchain TXs (x/interchaintxs)"]:::ibc
    end

    %% Protocol Definitions
    subgraph "Protocol Definitions"
        PD["Proto Definitions (proto)"]:::proto
        TP["Third-Party Proto (third_party/proto)"]:::proto
    end

    %% Infrastructure & DevOps
    subgraph "Infrastructure & DevOps"
        NS["Network Scripts (network)"]:::infra
        GH["GitHub Workflows (.github/workflows)"]:::infra
        DFIL["Dockerfile"]:::infra
        MF["Makefile"]:::infra
        SCPT["Scripts (scripts)"]:::infra
    end

    %% Connections from Application to Core Modules
    B -->|"routes_txns"| CM
    B -->|"routes_txns"| CR
    B -->|"routes_txns"| DX
    B -->|"routes_txns"| DF
    B -->|"routes_txns"| FB
    B -->|"routes_txns"| GF
    B -->|"routes_txns"| HP
    B -->|"routes_txns"| TF
    B -->|"routes_txns"| TR

    %% Core Modules interacting with Smart Contracts
    CM -->|"executes_contracts"| SC
    CM -->|"executes_contracts"| ST

    %% Core Modules communicating with Protocol Definitions
    CM ---|"grpc_calls"| PD
    CR ---|"grpc_calls"| PD
    DX ---|"grpc_calls"| PD
    DF ---|"grpc_calls"| PD
    FB ---|"grpc_calls"| PD
    GF ---|"grpc_calls"| PD
    HP ---|"grpc_calls"| PD
    TF ---|"grpc_calls"| PD
    TR ---|"grpc_calls"| PD

    %% Core Modules interfacing with IBC Modules
    CM ---|"ibc_comm"| IBCH
    CR ---|"ibc_comm"| IBCH
    DX ---|"ibc_comm"| IBCR
    DF ---|"ibc_comm"| ICQ
    FB ---|"ibc_comm"| ICTX

    %% IBC Modules linking back to Protocol Definitions
    IBCH -->|"ibc_packets"| PD
    IBCR -->|"ibc_packets"| PD
    ICQ -->|"ibc_packets"| PD
    ICTX -->|"ibc_packets"| PD

    %% Infrastructure & DevOps supporting the Node
    NS -->|"deploys"| A
    GH -->|"CI_CD"| A
    DFIL -->|"builds"| A
    MF -->|"builds"| A
    SCPT -->|"scripts_ops"| A

    %% Click Events
    click A "https://github.com/neutron-org/neutron/tree/main/cmd/neutrond"
    click B "https://github.com/neutron-org/neutron/tree/main/app"
    click CM "https://github.com/neutron-org/neutron/tree/main/x/contractmanager"
    click CR "https://github.com/neutron-org/neutron/tree/main/x/cron"
    click DX "https://github.com/neutron-org/neutron/tree/main/x/dex"
    click DF "https://github.com/neutron-org/neutron/tree/main/x/dynamicfees"
    click FB "https://github.com/neutron-org/neutron/tree/main/x/feeburner"
    click GF "https://github.com/neutron-org/neutron/tree/main/x/globalfee"
    click HP "https://github.com/neutron-org/neutron/tree/main/x/harpoon"
    click TF "https://github.com/neutron-org/neutron/tree/main/x/tokenfactory"
    click TR "https://github.com/neutron-org/neutron/tree/main/x/transfer"
    click IBCH "https://github.com/neutron-org/neutron/tree/main/x/ibc-hooks"
    click IBCR "https://github.com/neutron-org/neutron/tree/main/x/ibc-rate-limit"
    click ICQ "https://github.com/neutron-org/neutron/tree/main/x/interchainqueries"
    click ICTX "https://github.com/neutron-org/neutron/tree/main/x/interchaintxs"
    click PD "https://github.com/neutron-org/neutron/tree/main/proto"
    click TP "https://github.com/neutron-org/neutron/tree/main/third_party/proto"
    click SC "https://github.com/neutron-org/neutron/tree/main/contracts"
    click ST "https://github.com/neutron-org/neutron/tree/main/contracts_thirdparty"
    click NS "https://github.com/neutron-org/neutron/tree/main/network"
    click GH "https://github.com/neutron-org/neutron/tree/main/.github/workflows"
    click DFIL "https://github.com/neutron-org/neutron/tree/main/Dockerfile"
    click MF "https://github.com/neutron-org/neutron/tree/main/Makefile"
    click SCPT "https://github.com/neutron-org/neutron/tree/main/scripts"

    %% Styles
    classDef runtime fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef app fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef module fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef contracts fill:#DA70D6,stroke:#000,stroke-width:2px;
    classDef ibc fill:#40E0D0,stroke:#000,stroke-width:2px;
    classDef proto fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef infra fill:#FFB6C1,stroke:#000,stroke-width:2px;
```
