# hummingbot/gateway architecture

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

- Interactive diagram: https://gitdiagram.com/hummingbot/gateway
- Repository: https://github.com/hummingbot/gateway

## Overview

##### Project type and purpose
- This is a backend-focused API/CLI service (“Gateway”) written in TypeScript.
- Purpose: expose standardized REST endpoints (and equivalent CLI commands) to interact with blockchain networks (Ethereum, Solana) and DEX protocols (Jupiter, Meteora, Raydium, etc.).
- Key features: modular “connectors” for each DEX, “chain” modules per blockchain, centralized config management, and unified schemas for request validation.

##### File structure
Top-level:
- src/index.ts & src/app.ts – application & HTTP/CLI entry points
- src/commands/… – CLI command implementations (balance, start, build)
- src/https.ts – HTTPS server setup
- src/paths.ts, src/schemas/… – global path & schema definitions
- src/services/… – core services: config managers, connection manager, local storage, schema validators, logger, error handler
- src/config/… – configuration-related routes & validators
- src/chains/… – per-blockchain modules
- src/connectors/… – per-DEX modules
- src/wallet/… – wallet endpoints
- src/templates & /conf & /postman – scaffolding, configuration files, and API test tooling
Tests mirror src structure under test/.

##### README for additional insights
- Confirms Gateway provides both HTTP(S) server and CLI.
- Mentions Swagger auto-documentation.
- Describes new modular refactor:
- connectors follow Meteora reference implementation
- core interfaces in services/clmm-interface.ts

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        CLI["CLI Client"]:::clientPurple
        StartCmd["start"]:::clientPurple
        BalanceCmd["balance"]:::clientPurple
        BuildCmd["build"]:::clientPurple
    end

    CLI -->|runs| StartCmd
    CLI -->|runs| BalanceCmd
    CLI -->|runs| BuildCmd

    %% Entry Points
    subgraph "Entry & Dispatcher"
        Index["index.ts"]:::entryPink
        App["app.ts"]:::entryPink
        HTTPS["https.ts"]:::entryPink
        Paths["paths.ts"]:::entryPink
    end

    StartCmd -->|invokes| Index
    Index -->|loads| App
    Index -->|loads| HTTPS
    App -->|uses| Paths

    %% Routing Layer
    subgraph "Routing & Routes" 
        %% Chain Routes
        chainReq["chain.requests.ts"]:::routingBlue
        ethRoutes["ethereum.routes.ts"]:::routingBlue
        solRoutes["solana.routes.ts"]:::routingBlue
        %% Connector Routes
        connectorReq["connector.requests.ts"]:::routingBlue
        connectorRoutes["connector.routes.ts"]:::routingBlue
        jupRoutes["jupiter.routes.ts"]:::routingBlue
        metRoutes["meteora.routes.ts"]:::routingBlue
        rayRoutes["raydium.routes.ts"]:::routingBlue
        %% Config & Wallet
        configRoutes["config.routes.ts"]:::routingBlue
        walletRoutes["wallet.routes.ts"]:::routingBlue
    end

    App -->|HTTP requests| chainReq
    App --> connectorReq
    App --> configRoutes
    App --> walletRoutes

    chainReq --> ethRoutes
    chainReq --> solRoutes
    connectorReq --> connectorRoutes
    connectorRoutes --> jupRoutes
    connectorRoutes --> metRoutes
    connectorRoutes --> rayRoutes

    %% Controller & Validator Layer
    subgraph "Validators & Schemas"
        ethVal["ethereum.validators.ts"]:::routingBlue
        configVal["config.validators.ts"]:::routingBlue
        connVal["connector.validators.ts"]:::routingBlue
        chainSchema["chain-schema.ts"]:::routingBlue
        ammSchema["amm-schema.ts"]:::routingBlue
        clmmSchema["clmm-schema.ts"]:::routingBlue
        swapSchema["swap-schema.ts"]:::routingBlue
        JSONSchemas["JSON Schemas"]:::routingBlue
    end

    ethRoutes --> ethVal
    solRoutes --> chainSchema
    configRoutes --> configVal
    jupRoutes --> connVal
    metRoutes --> connVal
    rayRoutes --> connVal

    chainSchema --> JSONSchemas
    ammSchema --> JSONSchemas
    clmmSchema --> JSONSchemas
    swapSchema --> JSONSchemas

    %% Domain Logic
    subgraph "Domain Logic"
        subgraph "Chain Adapters" 
            Ethereum["Ethereum Adapter"]:::chainsOrange
            Solana["Solana Adapter"]:::chainsOrange
        end
        subgraph "Connector Plugins"
            Jupiter["Jupiter Connector"]:::connectorsGreen
            Meteora["Meteora Connector"]:::connectorsGreen
            Raydium["Raydium Connector"]:::connectorsGreen
        end
    end

    ethVal --> Ethereum
    chainSchema --> Ethereum
    connVal --> Jupiter
    connVal --> Meteora
    connVal --> Raydium

    %% Services & Infrastructure
    subgraph "Services & Infrastructure"
        ConfigMgr["config-manager-v2.ts"]:::servicesGray
        ConnMgr["connection-manager.ts"]:::servicesGray
        LocalStorage["local-storage.ts"]:::servicesGray
        Logger["logger.ts"]:::servicesGray
        ErrorHandler["error-handler.ts"]:::servicesGray
        ResponseWrap["response-wrapper.ts"]:::servicesGray
        RefCount["refcounting-closeable.ts"]:::servicesGray
        CommonInt["common-interfaces.ts"]:::servicesGray
    end

    Ethereum --> ConfigMgr
    Ethereum --> ConnMgr
    Ethereum --> LocalStorage
    Jupiter --> ConnMgr
    Meteora --> ConnMgr
    Raydium --> ConnMgr
    Jupiter --> CommonInt
    Meteora --> CommonInt
    Raydium --> CommonInt

    %% External Systems
    subgraph "External Systems"
        Blockchains["Blockchain Networks"]:::externalYellow
        DEXs["On-chain DEX Protocols"]:::externalYellow
        FileSystem["Local File System"]:::externalYellow
    end

    ConnMgr --> Blockchains
    Jupiter --> DEXs
    Meteora --> DEXs
    Raydium --> DEXs
    LocalStorage --> FileSystem
    ConfigMgr --> FileSystem

    %% Click Events
    click StartCmd "https://github.com/hummingbot/gateway/blob/main/src/commands/start.ts"
    click BalanceCmd "https://github.com/hummingbot/gateway/blob/main/src/commands/balance.ts"
    click BuildCmd "https://github.com/hummingbot/gateway/blob/main/src/commands/build.ts"
    click Index "https://github.com/hummingbot/gateway/blob/main/src/index.ts"
    click App "https://github.com/hummingbot/gateway/blob/main/src/app.ts"
    click HTTPS "https://github.com/hummingbot/gateway/blob/main/src/https.ts"
    click Paths "https://github.com/hummingbot/gateway/blob/main/src/paths.ts"
    click chainReq "https://github.com/hummingbot/gateway/blob/main/src/chains/chain.requests.ts"
    click ethRoutes "https://github.com/hummingbot/gateway/blob/main/src/chains/ethereum/ethereum.routes.ts"
    click solRoutes "https://github.com/hummingbot/gateway/blob/main/src/chains/solana/solana.routes.ts"
    click connectorReq "https://github.com/hummingbot/gateway/blob/main/src/connectors/connector.requests.ts"
    click connectorRoutes "https://github.com/hummingbot/gateway/blob/main/src/connectors/connector.routes.ts"
    click jupRoutes "https://github.com/hummingbot/gateway/blob/main/src/connectors/jupiter/jupiter.routes.ts"
    click metRoutes "https://github.com/hummingbot/gateway/blob/main/src/connectors/meteora/meteora.routes.ts"
    click rayRoutes "https://github.com/hummingbot/gateway/blob/main/src/connectors/raydium/raydium.routes.ts"
    click configRoutes "https://github.com/hummingbot/gateway/blob/main/src/config/config.routes.ts"
    click walletRoutes "https://github.com/hummingbot/gateway/blob/main/src/wallet/wallet.routes.ts"
    click ethVal "https://github.com/hummingbot/gateway/blob/main/src/chains/ethereum/ethereum.validators.ts"
    click configVal "https://github.com/hummingbot/gateway/blob/main/src/config/config.validators.ts"
    click connVal "https://github.com/hummingbot/gateway/blob/main/src/connectors/connector.validators.ts"
    click chainSchema "https://github.com/hummingbot/gateway/blob/main/src/schemas/chain-schema.ts"
    click ammSchema "https://github.com/hummingbot/gateway/blob/main/src/schemas/trading-types/amm-schema.ts"
    click clmmSchema "https://github.com/hummingbot/gateway/blob/main/src/schemas/trading-types/clmm-schema.ts"
    click swapSchema "https://github.com/hummingbot/gateway/blob/main/src/schemas/trading-types/swap-schema.ts"
    click JSONSchemas "https://github.com/hummingbot/gateway/tree/main/src/services/schema"
    click ConfigMgr "https://github.com/hummingbot/gateway/blob/main/src/services/config-manager-v2.ts"
    click ConnMgr "https://github.com/hummingbot/gateway/blob/main/src/services/connection-manager.ts"
    click LocalStorage "https://github.com/hummingbot/gateway/blob/main/src/services/local-storage.ts"
    click Logger "https://github.com/hummingbot/gateway/blob/main/src/services/logger.ts"
    click ErrorHandler "https://github.com/hummingbot/gateway/blob/main/src/services/error-handler.ts"
    click ResponseWrap "https://github.com/hummingbot/gateway/blob/main/src/services/response-wrapper.ts"
    click RefCount "https://github.com/hummingbot/gateway/blob/main/src/services/refcounting-closeable.ts"
    click CommonInt "https://github.com/hummingbot/gateway/blob/main/src/services/common-interfaces.ts"

    %% Styles
    classDef clientPurple fill:#D6CDFE,stroke:#7C3AED,color:#000
    classDef entryPink fill:#FECACA,stroke:#B91C1C,color:#000
    classDef routingBlue fill:#BFDBFE,stroke:#1D4ED8,color:#000
    classDef connectorsGreen fill:#D1FAE5,stroke:#059669,color:#000
    classDef chainsOrange fill:#FED7AA,stroke:#C2410C,color:#000
    classDef servicesGray fill:#E5E7EB,stroke:#6B7280,color:#000
    classDef externalYellow fill:#FEF3C7,stroke:#A16207,color:#000
```
