# chainbuff/open-sol-bot architecture

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

- Interactive diagram: https://gitdiagram.com/chainbuff/open-sol-bot
- Repository: https://github.com/chainbuff/open-sol-bot

## Overview

##### Main Components
- Telegram Bot Module (app/tg-bot):
– Handles user interactions via Telegram.
– Contains multiple conversation submodules (e.g., copytrade, wallet, home, monitor, swap, setting).
– Includes keyboards, middlewares, and notification logic.
- Trading Engine (app/trading):
– Implements trading functionality including “跟单” (copytrade), trade execution, settlements, and transaction building.
– Contains builders for different protocols (e.g., Raydium, Jupiter, Pump modules).
- Cache Preloader Service (app/cache-preloader):
– Responsible for preloading and caching important blockchain parameters like blockhashes, minimum balance (rent), and Raydium pool information.
- Wallet Tracker (app/wallet-tracker):
– Monitors wallet activities.
– Implements functionalities like transaction parsing, benchmarking, and subscription-based updates.
- Libraries (libs/):
– Contains several shared utilities and core libraries:
▫ Cache library (libs/cache) to encapsulate caching logic.
▫ Common functions and models (libs/common) used across modules.
▫ Database access (libs/db) with MySQL and Redis connectors.
▫ Services (libs/services) for higher-level business logic.
▫ gRPC interface (libs/yellowstone_grpc) for integration with external blockchain data sources (e.g., geyser protocol).
- External Dependencies and Infrastructure:
– MySQL and Redis, as defined in the configuration.
– RPC endpoints and API integrations (Helius, Shyft) for blockchain data.
– Docker infrastructure (Dockerfiles, docker-compose.yaml) to containerize components.
– Optional gRPC channels via the Yellowstone GRPC library.

##### Relationships and Data Flow
- The Telegram Bot module receives user commands (via conversations) and, through its various middlewares and services, routes these commands to the underlying Trading Engine.
- The Trading Engine communicates with:
– External APIs (Helius, Shyft) to get blockchain data.
– The Cache Preloader, which supplies fresh cached blockchain parameters needed for validation and rapid order execution.
- The Wallet Tracker independently monitors wallets (using websockets and/or gRPC subscriptions) and feeds data back to either the Telegram Bot (for live notifications) or to logging/alert systems.
- Libraries provide cross-cutting utilities:
– The DB library abstracts MySQL and Redis interactions.
– The Common library contains shared models and helper functions used by all modules.
– The gRPC library encapsulates connections to geyser and Solana storage endpoints.
- Each service is containerized (as indicated by Dockerfiles and docker-compose.yaml) and communicates through well-defined APIs or messaging channels.

##### Important Architectural Patterns and Design Principles
- Separation of Concerns: Different functionalities – Telegram interaction, trading logic, caching, and wallet tracking – are separated into distinct modules.
- Microservices/Containerization: Each component (tg-bot, trading, cache preloader, wallet tracker) can run as its own Docker container, easing deployment and scaling.
- Modular Libraries: The use of shared libraries promotes code reusability and clean separation between business logic and infrastructure concerns.
- Event-Driven Data Flow: Components (especially the wallet tracker and trading engine) likely use event-driven patterns for reacting to blockchain events.

##### Relevant Technologies, Frameworks, and Libraries
- Python 3.10+ (primary language)
- Docker & Docker Compose for containerization.
- MySQL and Redis as external data stores.
- gRPC (via the Yellowstone GRPC library)
- External APIs such as Helius and Shyft (for RPC endpoints)
- Telegram Bot API for interfacing with users (including conversation management, keyboards, and middlewares).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Styling Classes
    classDef service fill:#D3E5FF,stroke:#3A78B3,stroke-width:2px;
    classDef library fill:#F2D7D9,stroke:#C0392B,stroke-width:2px;
    classDef external fill:#D5F5E3,stroke:#27AE60,stroke-width:2px;
    classDef container fill:#F9E79F,stroke:#F1C40F,stroke-width:2px;
    classDef user fill:#EBDEF0,stroke:#8E44AD,stroke-width:2px;

    %% Actor
    User["User (Telegram)"]:::user

    %% Services
    subgraph "Services"
        TG["Telegram Bot Service\n(Handles Telegram commands)"]:::service
        Trading["Trading Engine\n(Executes trades & copytrade)"]:::service
        CachePreloader["Cache Preloader Service\n(Preloads blockchain cache)"]:::service
        WalletTracker["Wallet Tracker\n(Monitors wallet activities)"]:::service
    end

    %% Shared Libraries
    subgraph "Shared Libraries"
        LibCache["Cache Library"]:::library
        LibCommon["Common Functions/Models"]:::library
        LibDB["Database Access\n(MySQL/Redis connectors)"]:::library
        LibServices["Services Layer"]:::library
        LibGRPC["gRPC Interface\n(Yellowstone GRPC)"]:::library
    end

    %% External Systems and Dependencies
    subgraph "External Systems"
        MySQL[(MySQL)]:::external
        Redis[(Redis)]:::external
        ExternalRPC["External RPC\n(Helius/Shyft)"]:::external
        BlockchainData["Blockchain Data\n(gRPC Endpoints)"]:::external
    end

    %% Containerization Artifacts
    subgraph "Containerization"
        DockerCompose["Docker Compose\n(docker-compose.yaml)"]:::container
        DockerfileTG["Dockerfile (tg-bot)"]:::container
        DockerfileTrading["Dockerfile (trading)"]:::container
        DockerfileCache["Dockerfile (cache-preloader)"]:::container
        DockerfileWallet["Dockerfile (wallet-tracker)"]:::container
    end

    %% Relationships
    User -->|"SendsCommands"| TG
    TG -->|"RoutesCommands"| Trading
    Trading -->|"QueriesCache"| CachePreloader
    Trading -->|"CallsRPC"| ExternalRPC
    WalletTracker -->|"Monitors"| BlockchainData
    WalletTracker -->|"Notifies"| TG

    %% Service usage of libraries
    TG -->|"UsesLibrary"| LibCommon
    TG ---|"Utilizes"| LibGRPC
    Trading -->|"UsesLibrary"| LibServices
    Trading ---|"Utilizes"| LibGRPC
    CachePreloader -->|"UsesLibrary"| LibCache
    CachePreloader ---|"Utilizes"| LibGRPC
    WalletTracker -->|"UsesLibrary"| LibDB
    WalletTracker ---|"Utilizes"| LibGRPC

    %% External DB interactions
    Trading -->|"StoresData"| MySQL
    Trading -->|"CachesData"| Redis
    WalletTracker -->|"LogsData"| MySQL
    WalletTracker -->|"CachesData"| Redis

    %% Containerization context
    DockerCompose --- TG
    DockerCompose --- Trading
    DockerCompose --- CachePreloader
    DockerCompose --- WalletTracker
    DockerfileTG --- TG
    DockerfileTrading --- Trading
    DockerfileCache --- CachePreloader
    DockerfileWallet --- WalletTracker

    %% Click Events for Component Mapping
    click TG "https://github.com/chainbuff/open-sol-bot/tree/main/app/tg-bot"
    click Trading "https://github.com/chainbuff/open-sol-bot/tree/main/app/trading"
    click CachePreloader "https://github.com/chainbuff/open-sol-bot/tree/main/app/cache-preloader"
    click WalletTracker "https://github.com/chainbuff/open-sol-bot/tree/main/app/wallet-tracker"
    click LibCache "https://github.com/chainbuff/open-sol-bot/tree/main/libs/cache"
    click LibCommon "https://github.com/chainbuff/open-sol-bot/tree/main/libs/common"
    click LibDB "https://github.com/chainbuff/open-sol-bot/tree/main/libs/db"
    click LibServices "https://github.com/chainbuff/open-sol-bot/tree/main/libs/services"
    click LibGRPC "https://github.com/chainbuff/open-sol-bot/tree/main/libs/yellowstone_grpc"
    click DockerCompose "https://github.com/chainbuff/open-sol-bot/blob/main/docker-compose.yaml"
    click DockerfileTG "https://github.com/chainbuff/open-sol-bot/tree/main/app/tg-bot/Dockerfile"
    click DockerfileTrading "https://github.com/chainbuff/open-sol-bot/tree/main/app/trading/Dockerfile"
    click DockerfileCache "https://github.com/chainbuff/open-sol-bot/tree/main/app/cache-preloader/Dockerfile"
    click DockerfileWallet "https://github.com/chainbuff/open-sol-bot/tree/main/app/wallet-tracker/Dockerfile"
```
