# reo7sp/tgbot-cpp architecture

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

## Overview

##### Main Components
- Library Core: This includes the core classes that the users of the library interact with. For example, the primary classes are housed in the “include/tgbot” directory (e.g., Bot.h, Api.h, and various utility headers). The “src” directory holds the corresponding implementations (e.g., Api.cpp, Bot.cpp).
- Data Types and Parsers: The “include/tgbot/types” along with the corresponding “src/types” provide structures and helper functions to parse and model the Telegram API entities (Message, Chat, Update, etc.).
- Event Handling: The library supports event-driven programming, indicated by components like EventHandler.h and EventBroadcaster.h, which are central to reacting to incoming messages and commands.
- Tools, Tests, and Samples: The “samples” and “test” directories include various example bots and unit tests (using CMake build files) that demonstrate how to use the library. This separation shows a clear distinction between production-quality library code and extra material meant for learning, verifying, or demonstrating usage.

##### Relationships and Interactions
- The Bot acts as an orchestrator: Clients create an instance of the Bot and register event handlers (e.g., onCommand, onAnyMessage).
- The API module (exposed via Api.h/Api.cpp) communicates with Telegram’s servers. It interacts with the network layer to send HTTP requests/responses.
- The Network Layer is abstracted to allow for different implementations (e.g., Curl or Boost) which the API module can use interchangeably.
- The Data Types provide the intermediate representations of messages, updates, and other Telegram entities. The API layer converts raw HTTP data into these types using parsing utilities.
- The Event Handling component receives incoming updates (whether via long polling or webhook) and dispatches them to the appropriate event handlers registered by the bot.
- Samples demonstrate how to wire all the pieces together, showing the flow from the instantiation of the bot, setup of event handlers, to the initiation of a long polling loop or webhook server.

##### Architectural Patterns and Design Principles
- Abstraction & Modularity: The clear division of code into “include”/“src” for library components, “net” for network communications, “types” for data modeling, and “tools”/“samples” for auxiliary functions.
- Dependency Inversion: The network layer is pluggable; users can select a preferred HTTP client by choosing the appropriate implementation (e.g., Curl vs. Boost).
- Event-Driven Architecture: Rather than a monolithic procedural design, the library employs callbacks and events to handle diverse Telegram API updates.
- Separation of Concerns: The library cleanly separates API requests, network client implementations, and data handling, making it easier to maintain and extend.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Client Application Layer
    subgraph "Client Application"
        client["User Bot Code"]:::client
    end

    %% Library Public Interface
    subgraph "Library Public Interface"
        bot["TgBot::Bot"]:::core
        api["TgBot::Api"]:::core
        excep["TgBot::TgException"]:::core
    end

    %% Network Layer
    subgraph "Network Layer"
        curl["CurlHttpClient"]:::network
        boost["BoostHttpOnlySslClient"]:::network
        parser["HttpParser"]:::network
        longpoll["TgLongPoll"]:::network
        webhook["TgWebhookServer"]:::network
    end

    %% Data Types & Parsers
    subgraph "Data Types & Parsers"
        message["Message"]:::data
        update["Update"]:::data
        chat["Chat"]:::data
    end

    %% Event Handling
    subgraph "Event Handling"
        broadcaster["EventBroadcaster"]:::event
        handler["EventHandler"]:::event
    end

    %% External Dependency
    ext["Telegram Servers"]:::external

    %% Samples, Tests & Tools
    subgraph "Samples & Tests"
        sample["Echo Bot Sample"]:::sample
        test["Unit Tests"]:::test
        tools["Utility Tools"]:::tools
    end

    %% Connections
    client -->|"calls"| bot
    bot -->|"uses"| api
    api -->|"HTTP_Req/Res"| curl
    api -->|"HTTP_Req/Res"| boost
    api -->|"parses_data_with"| parser
    curl -->|"communicates_with"| ext
    boost -->|"communicates_with"| ext
    parser -->|"parses_into"| message
    parser -->|"parses_into"| update
    parser -->|"parses_into"| chat
    api -->|"fetches_updates"| longpoll
    longpoll -->|"polls"| ext
    api -->|"sends_webhook"| webhook
    webhook -->|"interacts_with"| ext
    bot -->|"handles_events_via"| broadcaster
    broadcaster -->|"dispatches_to"| handler
    handler -->|"triggers_callbacks_to"| client
    client -->|"demonstrates_usage_in"| sample
    sample -->|"verified_by"| test
    sample -->|"may_use"| tools

    %% Click Events for Library Core
    click bot "https://github.com/reo7sp/tgbot-cpp/blob/master/include/tgbot/Bot.h"
    click bot "https://github.com/reo7sp/tgbot-cpp/blob/master/src/Bot.cpp"
    click api "https://github.com/reo7sp/tgbot-cpp/blob/master/include/tgbot/Api.h"
    click api "https://github.com/reo7sp/tgbot-cpp/blob/master/src/Api.cpp"
    click excep "https://github.com/reo7sp/tgbot-cpp/blob/master/include/tgbot/TgException.h"
    click excep "https://github.com/reo7sp/tgbot-cpp/blob/master/src/TgException.cpp"

    %% Click Events for Network Layer
    click curl "https://github.com/reo7sp/tgbot-cpp/blob/master/include/tgbot/net/CurlHttpClient.h"
    click curl "https://github.com/reo7sp/tgbot-cpp/blob/master/src/net/CurlHttpClient.cpp"
    click boost "https://github.com/reo7sp/tgbot-cpp/blob/master/include/tgbot/net/BoostHttpOnlySslClient.h"
    click boost "https://github.com/reo7sp/tgbot-cpp/blob/master/src/net/BoostHttpOnlySslClient.cpp"
    click parser "https://github.com/reo7sp/tgbot-cpp/blob/master/include/tgbot/net/HttpParser.h"
    click parser "https://github.com/reo7sp/tgbot-cpp/blob/master/src/net/HttpParser.cpp"
    click longpoll "https://github.com/reo7sp/tgbot-cpp/blob/master/include/tgbot/net/TgLongPoll.h"
    click longpoll "https://github.com/reo7sp/tgbot-cpp/blob/master/src/net/TgLongPoll.cpp"
    click webhook "https://github.com/reo7sp/tgbot-cpp/blob/master/include/tgbot/net/TgWebhookServer.h"
    click longpoll "https://github.com/reo7sp/tgbot-cpp/blob/master/src/net/Url.cpp"

    %% Click Events for Data Types and Parsers
    click message "https://github.com/reo7sp/tgbot-cpp/blob/master/include/tgbot/types/Message.h"
    click update "https://github.com/reo7sp/tgbot-cpp/blob/master/include/tgbot/types/Update.h"
    click chat "https://github.com/reo7sp/tgbot-cpp/blob/master/include/tgbot/types/Chat.h"
    click message "https://github.com/reo7sp/tgbot-cpp/blob/master/src/types/InlineQueryResult.cpp"
    click update "https://github.com/reo7sp/tgbot-cpp/blob/master/src/types/BotCommandScope.cpp"
    click chat "https://github.com/reo7sp/tgbot-cpp/blob/master/src/types/ChatBoostSource.cpp"

    %% Click Events for Event Handling
    click broadcaster "https://github.com/reo7sp/tgbot-cpp/blob/master/include/tgbot/EventBroadcaster.h"
    click handler "https://github.com/reo7sp/tgbot-cpp/blob/master/include/tgbot/EventHandler.h"
    click handler "https://github.com/reo7sp/tgbot-cpp/blob/master/src/EventHandler.cpp"

    %% Click Events for Tools, Tests, and Samples
    click tools "https://github.com/reo7sp/tgbot-cpp/blob/master/include/tgbot/tools/FileTools.h"
    click tools "https://github.com/reo7sp/tgbot-cpp/blob/master/include/tgbot/tools/StringTools.h"
    click tools "https://github.com/reo7sp/tgbot-cpp/blob/master/src/tools/FileTools.cpp"
    click tools "https://github.com/reo7sp/tgbot-cpp/blob/master/src/tools/StringTools.cpp"
    click sample "https://github.com/reo7sp/tgbot-cpp/tree/master/samples/echobot"
    click sample "https://github.com/reo7sp/tgbot-cpp/tree/master/samples/echobot-curl-client"
    click sample "https://github.com/reo7sp/tgbot-cpp/tree/master/samples/echobot-webhook-server"
    click test "https://github.com/reo7sp/tgbot-cpp/blob/master/test/CMakeLists.txt"
    click test "https://github.com/reo7sp/tgbot-cpp/blob/master/test/main.cpp"

    %% Styles
    classDef core fill:#ffdead,stroke:#d2691e,stroke-width:2px;
    classDef network fill:#ffd700,stroke:#daa520,stroke-width:2px;
    classDef data fill:#98fb98,stroke:#2e8b57,stroke-width:2px;
    classDef event fill:#add8e6,stroke:#4682b4,stroke-width:2px;
    classDef external fill:#f08080,stroke:#cd5c5c,stroke-width:2px;
    classDef sample fill:#ffb6c1,stroke:#ff69b4,stroke-width:2px;
    classDef test fill:#dda0dd,stroke:#9932cc,stroke-width:2px;
    classDef tools fill:#e6e6fa,stroke:#9370db,stroke-width:2px;
    classDef client fill:#f5f5dc,stroke:#deb887,stroke-width:2px;
```
