TelePilot Backend Architecture

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• bot.py
• requirements.txt
• Dockerfile (Referenced via deployment instructions)
• .env.example (Referenced via configuration documentation)

The TelePilot backend consists of a Python-based Telegram bot designed to manage channel and group interactions through automated summarization and command processing. It functions as a long-running worker service that interfaces with the Telegram Bot API to process messages in real-time.

The system provides a local, dependency-light summarization engine that extracts key information from recent chat history or direct user input. While the core bot is a minimal Python script, the architecture supports complex management features including smart broadcasting, scheduled posting, and AI-powered insights.
Sources: README.md:3-12, bot.py:1-5

Core Component Overview

The backend architecture centers around a single-threaded event loop that polls for updates and manages state in-memory.

Update Polling Mechanism

The poll_updates function manages the continuous retrieval of new messages from Telegram. It uses the getUpdates method with long-polling to minimize network overhead. The system tracks an offset to ensure each message is processed exactly once.

The diagram shows the iterative polling cycle used to fetch data from the Telegram API.
Sources: bot.py:133-146

Message Processing Pipeline

The process_message function acts as the primary router for incoming data. It identifies commands, stores regular text messages for future summarization, and triggers appropriate response actions.

Command	Action	Description
/start	Health Check	Confirms bot status to the user.
/help	Information	Returns a list of available commands.
/summary	Summarization	Summarizes the last MAX_STORED_MESSAGES.
/summary <text>	Direct Summary	Summarizes the provided string immediately.

Sources: bot.py:108-130, README.md:8-12

Data Management and State

The bot maintains a volatile, in-memory cache of recent messages to facilitate summarization without requiring an external database.

In-Memory Storage

The system uses a defaultdict of deque objects to store messages per chat. Each deque is constrained by the MAX_STORED_MESSAGES limit, automatically discarding the oldest messages when the capacity is reached.

chat_messages: dict[int, deque[str]] = defaultdict(lambda: deque(maxlen=MAX_STORED_MESSAGES))

Sources: bot.py:32

Configuration Environment

The backend utilizes environment variables for operational parameters.

Variable	Type	Default	Usage
TELEGRAM_BOT_TOKEN	String	None	Authentication with Telegram API.
POLL_TIMEOUT	Integer	30	Seconds for long-poll connection.
MAX_STORED_MESSAGES	Integer	100	Limit of messages kept per chat.
SUMMARY_SENTENCES	Integer	5	Output length for summaries.

Sources: bot.py:21-26, README.md:46-52

Summarization Logic

The summarization module operates as a local extractive engine. It does not require external AI API keys for basic functionality.

1. Normalization: The system replaces common punctuation (!, ?) with periods and splits the text into individual sentences.
2. Filtering: It removes whitespace-only strings and empty sentences.
3. Extraction: The engine selects the first SUMMARY_SENTENCES (default 5) to form the summary.
4. Formatting: It joins the selected sentences and ensures the output is properly terminated.

The flow summarizes the extractive logic used to generate text overviews.
Sources: bot.py:82-97

API Integration

Communication with Telegram is handled through a custom telegram_api wrapper using urllib3.

Request Execution

The telegram_api function handles:

• Constructing the request URL with the BOT_TOKEN.
• JSON-encoding the payload.
• Managing request timeouts (configured via POLL_TIMEOUT).
• Validating the ok status of the response.
  Sources: bot.py:53-70

Sequence of a Command Response

When a user sends a /summary command, the following sequence occurs:

This sequence illustrates the interaction between the bot logic and the external Telegram API during a summary request.
Sources: bot.py:121-127, bot.py:133-146

Deployment Architecture

The backend is designed for containerized or service-based deployment.

Execution Environments

• Docker: Uses a multi-stage or simple build to run bot.py as a background worker.
• Systemd: Managed as a Linux service with Restart=always to ensure high availability.
• Worker Process: Compatible with platforms like Render or Railway using a Procfile worker definition.

Dependencies

The backend maintains a minimal footprint:

• urllib3: For HTTP requests to the Telegram API.
• python-dotenv: For configuration management.
• telebot: Underlying library for Telegram interactions.
  Sources: requirements.txt:1-4, README.md:61-94

The TelePilot backend architecture provides a robust foundation for Telegram management by combining efficient message polling with local text processing, ensuring quick response times without external API dependencies.
Sources: README.md:7-12