# averycung/lambo-bot architecture

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

- Interactive diagram: https://gitdiagram.com/averycung/lambo-bot
- Repository: https://github.com/averycung/lambo-bot

## Overview

##### Project type and purpose
- Lambo Bot is a Python-based Telegram bot service.
- It listens to chat messages, detects Solana token addresses, and replies with user-configured referral codes.
- Referral codes and chat-ownership records are stored in a MySQL database.
- The service runs as a single backend process (e.g., on Heroku via the Procfile).

##### File structure
- Top level:
- .env – environment variables (Telegram token, MySQL URL)
- Procfile – Heroku startup command
- requirements.txt – Python dependencies
- README.md – project documentation
- assets/ – static images for README; not part of runtime
- bot.py – entry point creating the Telegram Bot instance and registering handlers
- bot/
– __init__.py
– db.py – database connection and helpers
- This flat structure indicates a monolithic service with two logical layers:
1) Bot application code (message handlers, command implementations, referral logic)
2) Database access layer

##### README for additional insights
- Lists commands (/start, /help, /setcode, etc.)
- Describes two data tables:
- user referral codes (keyed by Telegram user ID)
- claimed chats (keyed by chat ID and owner ID)
- Emphasizes CA (contract address) detection using Base58Check

a. Main components
- Telegram Bot Service (Python runtime)
- Message Receiver / Dispatcher
- Command Handlers (start, setcode, claim, etc.)
- CA Detection Engine
- Referral Code Service
- Database Access Layer
- External Service: Telegram Bot API
- Data Store: MySQL Database
- Hosting Platform / Runtime Environment (e.g., Heroku, Docker, or other)
b. Relationships and interactions
1. Telegram users send messages → Telegram Bot API
2. Bot Service polls or receives webhooks from Telegram API
3. Incoming messages are dispatched to appropriate command handler or CA detection module
4. Handlers query/update MySQL (via db.py) for user codes or chat ownership
5. Bot Service sends replies back through Telegram API
c. Architectural patterns / design principles
- Event-driven: on-message callbacks registered in bot.py
- Layered separation between application logic and persistence (db.py)
- Single-process monolith for simplicity and low latency
d. Key technologies
- python-telegram-bot (or similar) library
- MySQL (hosted via environment variable)
- Heroku (via Procfile) or any container/VM
- Environment variables in .env for secrets

##### Detail
- Command handler as a separate sub-component if desired
- Procfile under the hosting/runtime component
- Data model at a high level: two tables with primary keys

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Participant
    User["Telegram User"]:::external
    TelegramAPI["Telegram Bot API"]:::external

    %% Bot Service Container
    subgraph "Bot Service (Python Monolith)" 
        direction TB
        BotEntry["Entry Point / Dispatcher\n(bot.py)"]:::core
        CAEngine["CA Detection Engine\n(Base58Check parser)"]:::core
        ReferralService["Referral Code Service"]:::core
        DBAccess["Database Access Layer\n(bot/db.py)"]:::core
    end

    %% Data Store
    MySQLDB["MySQL Database\n(user_codes, chat_owners)"]:::data

    %% Infrastructure / Hosting
    subgraph "Hosting & Configuration" 
        direction TB
        EnvConfig["Environment Variables\n(.env)"]:::infra
        Hosting["Runtime Config\n(Procfile)"]:::infra
    end

    %% Project Documentation & Dependencies
    subgraph "Project Files" 
        direction TB
        Dependencies["Python Dependencies\n(requirements.txt)"]:::infra
        Docs["Project Documentation\n(README.md)"]:::infra
    end

    %% Relationships
    User -->|"sends messages"| TelegramAPI
    TelegramAPI -->|"webhook/poll"| BotEntry
    BotEntry -->|"dispatches to"| CAEngine
    BotEntry -->|"dispatches to"| ReferralService
    CAEngine -->|"uses"| DBAccess
    ReferralService -->|"uses"| DBAccess
    DBAccess -->|"queries/updates"| MySQLDB
    BotEntry -->|"sends replies"| TelegramAPI

    %% Hosting connections
    Hosting -->|uses| EnvConfig
    Hosting -->|runs| BotEntry

    %% Click Events
    click BotEntry "https://github.com/averycung/lambo-bot/blob/main/bot.py"
    click DBAccess "https://github.com/averycung/lambo-bot/blob/main/bot/db.py"
    click EnvConfig "https://github.com/averycung/lambo-bot/blob/main/.env"
    click Hosting "https://github.com/averycung/lambo-bot/tree/main/Procfile"
    click Dependencies "https://github.com/averycung/lambo-bot/blob/main/requirements.txt"
    click Docs "https://github.com/averycung/lambo-bot/blob/main/README.md"

    %% Styles
    classDef external fill:#fdd,stroke:#b33,stroke-width:1px;
    classDef core fill:#dfd,stroke:#393,stroke-width:1px;
    classDef data fill:#ddf,stroke:#339,stroke-width:1px;
    classDef infra fill:#ffd,stroke:#993,stroke-width:1px;
```
