# eternnoir/pytelegrambotapi architecture

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

- Interactive diagram: https://gitdiagram.com/eternnoir/pytelegrambotapi
- Repository: https://github.com/eternnoir/pytelegrambotapi

## Overview

##### Project type and purpose
- This is an open-source Python client library (“pyTelegramBotAPI”) for the Telegram Bot HTTP API.
- It provides both synchronous (TeleBot) and asynchronous (AsyncTeleBot) interfaces, plus a rich ecosystem of handlers, filters, middleware, storage backends, state managers, utilities, and extensions.
- The examples folder demonstrates usage scenarios (echo bots, webhooks, middleware, serverless, etc.).

##### File structure
Top level:
- telebot/        ← core library modules
- examples/       ← sample bots and integration patterns
- docs/           ← Sphinx documentation sources
- tests/          ← unit tests against core and types
- config files    ← CI (.travis.yml, GitHub Actions), packaging (pyproject.toml, requirements.txt), .gitignore, LICENSE

Inside telebot/:
- apihelper.py                     ← HTTP adapter (requests for sync, aiohttp for async)
- async_telebot.py                 ← AsyncTeleBot entry point
- handler_backends.py              ← polling & webhook strategy implementations
- asyncio_handler_backends.py      ← async equivalents
- custom_filters.py                ← base classes for user-defined filters
- formatting.py, util.py           ← utility functions (string splitting, update types)
- callback_data.py                 ← tools for callback‐data parsing
- states/                          ← sync & async state management and middleware
- storage/                         ← storage strategy interfaces/implementations (memory, pickle, redis)
- types.py                         ← data model classes mapping Telegram JSON to Python objects
- ext/                             ← extensions (reloaders, webhook helpers)
- version.py                       ← library version

##### README for architecture hints
- Describes TeleBot vs AsyncTeleBot, middleware patterns, filters, webhook vs polling, storage & state abstractions.

##### Detailed capture of essential architectural elements
- Filter matching sequence.
- Storage interface abstraction with MemoryStorage, PickleStorage, RedisStorage as implementations.
- Call out ext/webhooks and ext/reloader as opt-in features.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User
    UserCode["User Code (Example Bot)"]:::external

    %% Core Client Layer
    subgraph "Core Client Layer"
        direction TB
        TeleBot["TeleBot (Sync)"]:::core
        AsyncTeleBot["AsyncTeleBot (Async)"]:::core
    end

    %% HTTP Adapter
    subgraph "HTTP Adapter" 
        direction TB
        APIHelperSync["apihelper (requests)"]:::io
        APIHelperAsync["asyncio_helper (aiohttp)"]:::io
    end

    %% Dispatch Pipeline
    subgraph "Update Dispatch Pipeline"
        direction TB
        HandlerBackendSync["HandlerBackends (polling/webhook)"]:::core
        HandlerBackendAsync["AsyncioHandlerBackends"]:::core
        MiddlewareSync["Middleware Chain (pre_process/post_process)"]:::core
        MiddlewareAsync["Asyncio Middleware Chain"]:::core
        FilterSync["Filter Engine"]:::core
        FilterAsync["Async Filter Engine"]:::core
        HandlerInvocation["Handler Invocation"]:::core
    end

    %% Data & Utils
    subgraph "Data Models & Utilities"
        direction TB
        Types["types.py (JSON⇄Object)"]:::data
        CallbackUtil["callback_data.py"]:::data
        Formatting["formatting.py"]:::util
        Util["util.py"]:::util
    end

    %% State & Storage
    subgraph "State & Storage"
        direction TB
        subgraph "State Managers"
            ContextSync["context.py (sync)"]:::core
            ContextAsync["context.py (async)"]:::core
        end
        subgraph "Storage Strategies"
            BaseSync["base_storage.py"]:::io
            MemorySync["memory_storage.py"]:::io
            PickleSync["pickle_storage.py"]:::io
            RedisSync["redis_storage.py"]:::io
            BaseAsync["base_storage.py"]:::io
            MemoryAsync["memory_storage.py"]:::io
            PickleAsync["pickle_storage.py"]:::io
            RedisAsync["redis_storage.py"]:::io
        end
    end

    %% Extensions
    subgraph "Extensions & Plugins"
        direction TB
        WebhookSync["ext/sync/webhooks"]:::extension
        WebhookAsync["ext/aio/webhooks"]:::extension
        Reloader["ext/reloader"]:::extension
    end

    %% Relationships
    UserCode -->|instantiates| TeleBot
    UserCode -->|instantiates| AsyncTeleBot

    TeleBot -->|uses| HandlerBackendSync
    AsyncTeleBot -->|uses| HandlerBackendAsync

    HandlerBackendSync -->|HTTP| APIHelperSync
    HandlerBackendAsync -->|HTTP| APIHelperAsync

    APIHelperSync -->|calls Telegram API| ExternalAPI["Telegram API"]:::external
    APIHelperAsync -->|calls Telegram API| ExternalAPI

    ExternalAPI -->|response JSON| APIHelperSync
    ExternalAPI -->|response JSON| APIHelperAsync

    APIHelperSync -->|parses| Types
    APIHelperAsync -->|parses| Types

    Types -->|Update objects| HandlerBackendSync
    Types -->|Update objects| HandlerBackendAsync

    HandlerBackendSync --> MiddlewareSync
    HandlerBackendAsync --> MiddlewareAsync

    MiddlewareSync --> FilterSync
    MiddlewareAsync --> FilterAsync

    FilterSync --> HandlerInvocation
    FilterAsync --> HandlerInvocation

    HandlerInvocation --> TeleBot
    HandlerInvocation --> AsyncTeleBot

    TeleBot -->|bot methods| APIHelperSync
    AsyncTeleBot -->|bot methods| APIHelperAsync

    %% State & Storage injection
    MiddlewareSync --> ContextSync
    MiddlewareAsync --> ContextAsync

    ContextSync --> MemorySync
    ContextSync --> PickleSync
    ContextSync --> RedisSync

    ContextAsync --> MemoryAsync
    ContextAsync --> PickleAsync
    ContextAsync --> RedisAsync

    %% Extensions hooks
    TeleBot --> WebhookSync
    AsyncTeleBot --> WebhookAsync
    TeleBot --> Reloader

    %% Data & Utils usage
    TeleBot --> Formatting
    TeleBot --> Util
    AsyncTeleBot --> Formatting
    AsyncTeleBot --> Util
    HandlerInvocation --> CallbackUtil

    %% Click Events
    click TeleBot "https://github.com/eternnoir/pytelegrambotapi/blob/master/telebot/__init__.py"
    click AsyncTeleBot "https://github.com/eternnoir/pytelegrambotapi/blob/master/telebot/async_telebot.py"
    click APIHelperSync "https://github.com/eternnoir/pytelegrambotapi/blob/master/telebot/apihelper.py"
    click APIHelperAsync "https://github.com/eternnoir/pytelegrambotapi/blob/master/telebot/asyncio_helper.py"
    click HandlerBackendSync "https://github.com/eternnoir/pytelegrambotapi/blob/master/telebot/handler_backends.py"
    click HandlerBackendAsync "https://github.com/eternnoir/pytelegrambotapi/blob/master/telebot/asyncio_handler_backends.py"
    click ContextSync "https://github.com/eternnoir/pytelegrambotapi/blob/master/telebot/states/sync/context.py"
    click MiddlewareSync "https://github.com/eternnoir/pytelegrambotapi/blob/master/telebot/states/sync/middleware.py"
    click ContextAsync "https://github.com/eternnoir/pytelegrambotapi/blob/master/telebot/states/asyncio/context.py"
    click MiddlewareAsync "https://github.com/eternnoir/pytelegrambotapi/blob/master/telebot/states/asyncio/middleware.py"
    click FilterSync "https://github.com/eternnoir/pytelegrambotapi/blob/master/telebot/custom_filters.py"
    click FilterAsync "https://github.com/eternnoir/pytelegrambotapi/blob/master/telebot/asyncio_filters.py"
    click Types "https://github.com/eternnoir/pytelegrambotapi/blob/master/telebot/types.py"
    click CallbackUtil "https://github.com/eternnoir/pytelegrambotapi/blob/master/telebot/callback_data.py"
    click BaseSync "https://github.com/eternnoir/pytelegrambotapi/blob/master/telebot/storage/base_storage.py"
    click MemorySync "https://github.com/eternnoir/pytelegrambotapi/blob/master/telebot/storage/memory_storage.py"
    click PickleSync "https://github.com/eternnoir/pytelegrambotapi/blob/master/telebot/storage/pickle_storage.py"
    click RedisSync "https://github.com/eternnoir/pytelegrambotapi/blob/master/telebot/storage/redis_storage.py"
    click BaseAsync "https://github.com/eternnoir/pytelegrambotapi/blob/master/telebot/asyncio_storage/base_storage.py"
    click MemoryAsync "https://github.com/eternnoir/pytelegrambotapi/blob/master/telebot/asyncio_storage/memory_storage.py"
    click PickleAsync "https://github.com/eternnoir/pytelegrambotapi/blob/master/telebot/asyncio_storage/pickle_storage.py"
    click RedisAsync "https://github.com/eternnoir/pytelegrambotapi/blob/master/telebot/asyncio_storage/redis_storage.py"
    click WebhookSync "https://github.com/eternnoir/pytelegrambotapi/blob/master/telebot/ext/sync/webhooks.py"
    click WebhookAsync "https://github.com/eternnoir/pytelegrambotapi/blob/master/telebot/ext/aio/webhooks.py"
    click Reloader "https://github.com/eternnoir/pytelegrambotapi/blob/master/telebot/ext/reloader.py"
    click Formatting "https://github.com/eternnoir/pytelegrambotapi/blob/master/telebot/formatting.py"
    click Util "https://github.com/eternnoir/pytelegrambotapi/blob/master/telebot/util.py"

    %% Styles
    classDef core fill:#D6EAF8,stroke:#3498DB
    classDef io fill:#FDEBD0,stroke:#E67E22
    classDef data fill:#EAECEE,stroke:#95A5A6
    classDef util fill:#EAECEE,stroke:#95A5A6
    classDef extension fill:#D5F5E3,stroke:#27AE60
    classDef external fill:#F8F9F9,stroke:#BDC3C7,stroke-dasharray: 5 5
```
