# osmosis-labs/osmosis architecture

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

- Interactive diagram: https://gitdiagram.com/osmosis-labs/osmosis
- Repository: https://github.com/osmosis-labs/osmosis

## Overview

##### Main Components
- Modules/Keepers: The project is organized modularly. Directories like “app/keepers”, “app/params”, “app/upgrades”, and all the “x/…” directories (e.g., concentrated‑liquidity, gamm, lockup, incentives, poolmanager, txfees, etc.) represent individual modules implementing features such as liquidity pools, staking, fee handling, and upgrades. They follow the pattern common in Cosmos‑SDK applications: each module has a “keeper” (state management) and “handlers” to process messages.
- Consensus & IBC Interface: Although not directly visible as a Tendermint repository, the node runs alongside Tendermint (as required by Cosmos‑SDK), and there is extensive support for IBC (inter‑blockchain communication) visible in directories like “proto/osmosis” (which defines IBC modules and related dependencies) and “ingest” that manages block indexing and state updates.
- CosmWasm Smart Contract Infrastructure: The “cosmwasm” directory and the “wasmbinding” folder indicate that Osmosis integrates Rust‑based smart contracts. This layer manages smart contracts for additional DeFi functionality.
- Auxiliary Components:
– The “ingest” and “sqs” directories describe services for block ingestion/indexing and external message processing.
– “client” and “scripts” directories include various CLI tools, documentation generators, testing harnesses, and deployment automation.
– “proto” hosts Protocol Buffer definitions to support gRPC API interactions across modules.
– A comprehensive “tests” directory ensures end‑to‑end, integration, and simulation testing.
– “x” contains many “extended” modules (e.g., concentrated‑liquidity, swapstrategy, smart‑account, tokenfactory) that add specialized protocols beyond basic Cosmos‑SDK functionality.

##### Relationships and Interactions
- At the Node level, include a separation between:
- Ingestion services (“ingest”, “sqs”) provide external indexing and data processing – these can be drawn as supporting services that subscribe to block events and update external state.
- Developer and deployment tooling (scripts, CI/CD workflows) reinforce testing, simulation, and release – include a “DevOps / Tooling” section.

##### Architectural Patterns and Design Principles
- The system follows a modular, layered architecture (typical of Cosmos‑SDK apps) with clear separation between consensus, application logic, module keepers, and smart contract runtimes.
- Emphasis on upgradeability: the “app/upgrades” folder and versioned upgrades (v10 to v29) show extensibility and change propagation.
- Clear API contracts defined via Protobufs show how modules communicate internally and externally (gRPC and REST interfaces).
- Separation of concerns in testing, simulation, and client command handling.

##### Relevant Technologies/Frameworks
- Languages: Go (majority of core blockchain code), Rust (for CosmWasm smart contracts).
- Cosmos‑SDK as the underlying framework.
- Tendermint for consensus.
- Docker & GitHub Actions for CI and containerized deployments (observable through Dockerfiles, .github/workflows).
- GRPC and Protobuf (from the “proto” directory) for service interfaces.
- Additional native packages and libraries in “osmoutils” for helper functions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Entities
    External["External Clients & Validators"]:::external

    %% Consensus Layer
    Tendermint["Tendermint Consensus"]:::consensus

    %% Application Layer
    CoreApp["Core Application (app/app.go, app/ante.go)"]:::app
    CLI["CLI Interface (cmd/osmosisd)"]:::app

    %% Modules & Keepers
    subgraph "Modules & Keepers"
        Keeper["Application Keepers (app/keepers)"]:::modules
        subgraph "x Modules"
            CL["Concentrated Liquidity (x/concentrated-liquidity)"]:::modules
            GAMM["GAMM (x/gamm)"]:::modules
            Lockup["Lockup (x/lockup)"]:::modules
            Incentives["Incentives (x/incentives)"]:::modules
            PoolManager["Pool Manager (x/poolmanager)"]:::modules
            TxFees["Tx Fees (x/txfees)"]:::modules
        end
    end

    %% Consensus & IBC Interface
    IBC["IBC & Protobufs (proto/osmosis)"]:::consensus
    BlockIngest["Block Ingestion (ingest)"]:::aux
    SQS["SQS Service (ingest/sqs)"]:::aux

    %% CosmWasm Smart Contract Infrastructure
    CosmWasm["CosmWasm Runtime (cosmwasm)"]:::cosmos
    WasmBinding["Smart Contract Binding (wasmbinding)"]:::cosmos

    %% Auxiliary & DevOps Tools
    subgraph "Auxiliary & DevOps Tools"
        ClientTools["Client Tools (client)"]:::aux
        CLIScripts["CLI Scripts (cmd/osmosisd/cmd)"]:::aux
        CICD["CI/CD Workflows (.github/workflows)"]:::aux
        Scripts["Deployment Scripts (scripts)"]:::aux
        Tests["Tests Suite (tests)"]:::aux
        Simulation["Simulation Framework (simulation)"]:::aux
        APIDefs["API Definitions (proto)"]:::aux
    end

    %% Connections
    External -->|"sends_transactions"| Tendermint
    Tendermint -->|"forwards_blocks"| CoreApp
    Tendermint -->|"publishes_events"| BlockIngest
    CoreApp -->|"processes_CLI"| CLI
    CoreApp -->|"dispatches_tx"| Keeper
    Keeper -->|"calls_module_logic"| CL
    Keeper -->|"calls_module_logic"| GAMM
    Keeper -->|"calls_module_logic"| Lockup
    Keeper -->|"calls_module_logic"| Incentives
    Keeper -->|"calls_module_logic"| PoolManager
    Keeper -->|"calls_module_logic"| TxFees
    CoreApp -->|"executes_contracts"| CosmWasm
    CosmWasm -->|"binds_contracts"| WasmBinding
    BlockIngest --> SQS
    External -->|"queries_via_CLI"| ClientTools
    External -->|"uses_CLI_Scripts"| CLIScripts
    External -->|"fetches_API"| APIDefs
    ClientTools -->|"supports_CI"| CICD
    CICD -->|"triggers_scripts"| Scripts
    CICD -->|"runs_tests"| Tests
    Tests -->|"simulates"| Simulation
    IBC -->|"interfaces_with"| Keeper
    IBC -->|"defines_contracts"| CoreApp

    %% Click Events
    click CoreApp "https://github.com/osmosis-labs/osmosis/blob/main/app/app.go"
    click CLI "https://github.com/osmosis-labs/osmosis/tree/main/cmd/osmosisd"
    click Keeper "https://github.com/osmosis-labs/osmosis/tree/main/app/keepers"
    click CL "https://github.com/osmosis-labs/osmosis/tree/main/x/concentrated-liquidity"
    click GAMM "https://github.com/osmosis-labs/osmosis/tree/main/x/gamm"
    click Lockup "https://github.com/osmosis-labs/osmosis/tree/main/x/lockup"
    click Incentives "https://github.com/osmosis-labs/osmosis/tree/main/x/incentives"
    click PoolManager "https://github.com/osmosis-labs/osmosis/tree/main/x/poolmanager"
    click TxFees "https://github.com/osmosis-labs/osmosis/tree/main/x/txfees"
    click IBC "https://github.com/osmosis-labs/osmosis/tree/main/proto/osmosis"
    click BlockIngest "https://github.com/osmosis-labs/osmosis/tree/main/ingest"
    click SQS "https://github.com/osmosis-labs/osmosis/tree/main/ingest/sqs"
    click CosmWasm "https://github.com/osmosis-labs/osmosis/tree/main/cosmwasm"
    click WasmBinding "https://github.com/osmosis-labs/osmosis/tree/main/wasmbinding"
    click ClientTools "https://github.com/osmosis-labs/osmosis/tree/main/client"
    click CLIScripts "https://github.com/osmosis-labs/osmosis/tree/main/cmd/osmosisd/cmd"
    click CICD "https://github.com/osmosis-labs/osmosis/tree/main/.github/workflows"
    click Scripts "https://github.com/osmosis-labs/osmosis/tree/main/scripts"
    click Tests "https://github.com/osmosis-labs/osmosis/tree/main/tests"
    click Simulation "https://github.com/osmosis-labs/osmosis/tree/main/simulation"
    click APIDefs "https://github.com/osmosis-labs/osmosis/tree/main/proto"

    %% Styles
    classDef external fill:#ffefc6,stroke:#b58900,stroke-width:2px;
    classDef consensus fill:#dff0d8,stroke:#859900,stroke-width:2px;
    classDef app fill:#cce5ff,stroke:#007bff,stroke-width:2px;
    classDef modules fill:#f8d7da,stroke:#dc3545,stroke-width:2px;
    classDef cosmos fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
    classDef aux fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
```
