How frozsgy/odtu-telegram-bot works
Project type and purpose
• This is a backend service: a Telegram Bot, written in Python, that interacts with users via the Telegram Bot API, processes messages, logs activity, and persists data in a PostgreSQL database.
• There is no user-facing GUI; the bot runs as a daemon (or in Docker) and communicates solely via HTTP calls to Telegram and SQL calls to Postgres.
File structure
• Top-level files:
• driver.py – the entry point that parses command-line flags, sets up logging, database connections, and starts the bot loop
• bot.py – module that encapsulates Telegram API interactions (polling or webhook, update dispatch)
• message.py / responses.py / turkish.py – business logic: parsing incoming messages, selecting or generating responses (including language-specific helpers)
• db.py – layer for database connectivity and SQL operations (init-tables.sql, backups folder)
• logger.py – application logging wrapper (to console or database, depending on flags)
• Dockerfile / docker-compose.yml – containerization and service definition
• init-tables.sql – schema definition
• requirements.txt / env – dependency definitions and environment variable placeholders
• No separate frontend directory; this is a monolithic, single-service architecture.
Key README insights
• Uses Python 3, Requests library, PostgreSQL
• Can run directly via Python or packaged in Docker, or installed as a systemd service
• Supports two modes: verbose console output, or logging to the database
a. Main components
1. Telegram External API (cloud service)
2. Bot Application Container/Process
– driver.py (orchestrator)
– bot.py (API client)
– Business Logic Modules (message.py, responses.py, turkish.py)
– Data Access Layer (db.py)
– Logging Layer (logger.py)
3. PostgreSQL Database (with init-tables.sql schema and backups)
4. Deployment/Orchestration
– Docker Engine / docker-compose
– Systemd service on Linux (alternate)
b. Relationships and interactions
– Bot Application polls or receives webhooks from the Telegram API → passes raw updates to business logic
– Business logic modules parse the update, call db.py to read/write data, pass messages to responses.py/turkish.py
– bot.py uses Requests to send HTTP replies back to Telegram API
– logger.py records events to console or writes logs into PostgreSQL
– Docker Compose coordinates the Bot container and a Postgres container (if using Docker), sets up environment variables and networking
– Systemd uses driver.py directly if running outside Docker
c. Architectural patterns / design principles
– Layered architecture:
1. Orchestration layer (driver.py)
2. API client layer (bot.py)
3. Business-domain layer (message/responses/turkish)
4. Data layer (db.py + PostgreSQL)
5. Cross-cutting concerns: logging (logger.py)
– Separation of concerns: API calls, business logic, data access, and logging are each in distinct modules
d. Key technologies
– Python 3, Requests library
– PostgreSQL (psycopg2)
– Docker, docker-compose
– systemd on Linux (for production service)