Skip to content

pyTMbot Architecture

This document describes the current runtime architecture.

Source of truth:

  • pytmbot/main.py
  • pytmbot/pytmbot_instance.py
  • pytmbot/handlers/
  • pytmbot/middleware/
  • pytmbot/adapters/
  • pytmbot/plugins/
  • pytmbot/webhook.py
  • pytmbot/health_system/

Runtime Shape

pyTMbot is a synchronous Telegram bot built on pyTelegramBotAPI.

Core entrypoints:

  • pytmbot/main.py: process launcher, signal handling, health startup, runtime supervision
  • pytmbot/pytmbot_instance.py: bot construction, middleware setup, handler registration, plugin loading, polling / webhook start

Runtime modes:

  • polling mode
  • webhook mode

Startup Sequence

High-level flow:

  1. CLI arguments are parsed.
  2. BotLauncher validates the environment and builds PyTMBot.
  3. PyTMBot creates the TeleBot instance.
  4. Bot commands, description, and short description are published.
  5. Middleware chain is registered.
  6. Handler chain is registered.
  7. Requested plugins are loaded.
  8. The fallback handler for unrecognized private-chat text is registered last.
  9. Health monitoring is initialized.
  10. Runtime enters polling or webhook mode.

Major Subsystems

Configuration

  • pytmbot/settings.py
  • pytmbot/models/settings_model.py
  • pytmbot/globals.py

Responsibilities:

  • load pytmbot.yaml
  • validate and migrate config
  • expose shared runtime settings objects

Core Runtime

  • pytmbot/main.py
  • pytmbot/pytmbot_instance.py

Responsibilities:

  • process lifecycle
  • startup / shutdown
  • polling supervision and restart strategy
  • webhook fallback to polling

Handlers

  • pytmbot/handlers/bot_handlers/
  • pytmbot/handlers/docker_handlers/
  • pytmbot/handlers/server_handlers/
  • pytmbot/handlers/auth_processing/

Responsibilities:

  • Telegram command handling
  • callback handling
  • Docker UI flows
  • server status views
  • 2FA interaction flows

Middleware

  • update_dedup
  • access_control
  • rate_limit
  • callback_ack
  • session_manager
  • session_wrapper

Responsibilities:

  • duplicate update rejection
  • allowlist enforcement
  • request throttling
  • acknowledging callback queries that handlers left unanswered
  • authentication state
  • 2FA protection for sensitive handlers

Adapters

  • pytmbot/adapters/docker/
  • pytmbot/adapters/psutil/
  • pytmbot/db/influxdb_interface.py

Responsibilities:

  • Docker API access
  • host metrics collection
  • InfluxDB storage and queries

Parsers And Templates

  • pytmbot/parsers/
  • pytmbot/templates/

Responsibilities:

  • Jinja2 template rendering for classic and rich Telegram content
  • render validation
  • cache management
  • output formatting for Telegram responses, including Rich Messages via InputRichMessage(html=...) helpers in pytmbot/handlers/handlers_util/rich_messages.py
  • rich HTML limits and fallbacks in pytmbot/utils/rich_html.py: measuring and trimming content to Telegram limits, plain-text conversion for rejected rich payloads, and structural validation used by tests

Plugins

  • pytmbot/plugins/plugin_manager.py
  • pytmbot/plugins/plugin_interface.py
  • built-in packages in pytmbot/plugins/monitor/ and pytmbot/plugins/outline/

Responsibilities:

  • dynamic extension loading
  • plugin metadata registration
  • plugin UI integration

Webhook Runtime

  • pytmbot/webhook.py

Responsibilities:

  • FastAPI / Uvicorn server
  • webhook registration
  • request authentication
  • Telegram IP validation
  • rate limiting and ban persistence

Health System

  • pytmbot/health_system/
  • pytmbot/parsers/health_checker.py

Responsibilities:

  • component-level health checks
  • periodic summary generation
  • startup and runtime observability

Request Flow

Polling mode:

  1. Telegram update enters TeleBot.
  2. Class middleware runs.
  3. Matching handler executes.
  4. Templates / adapters / plugins provide response data.
  5. Response is sent through Telegram API.

Webhook mode:

  1. FastAPI route validates webhook path and secret token.
  2. Client IP is validated against Telegram ranges.
  3. Webhook rate limiting is applied.
  4. Update payload is validated into UpdateModel.
  5. TeleBot.process_new_updates() handles the update.

Shared State

The codebase intentionally uses a few shared singletons / cached objects:

  • global settings and derived config objects
  • SessionManager
  • HealthStatus
  • plugin manager
  • parser caches

These are part of the runtime design and are referenced by both application code and tests.