How vo1dee/psychochauffeurbot works
Project Type and Purpose
• This is a monolithic, full-stack Telegram bot written in Python.
• Its purpose is to handle incoming Telegram messages and commands, process them via various feature modules (video downloading, GPT chat, weather, reminders, geomagnetics, etc.), interact with external APIs, maintain persistent data (reminders, logs), and send responses back to Telegram chats.
File Structure
• Top-level files:
• main.py – entry point that registers handlers and starts the bot
• config/ – configuration for group and private chats
• modules/ – feature modules implementing all bot capabilities
• data/ – placeholder for persistent storage files (logs, downloads, reminders)
• tests/ – unit tests for each module
• utils/ – supporting utility scripts (e.g., API diagnosis)
• modules/ substructure reveals clearly delineated features:
• video_downloader.py
• gpt.py
• weather.py
• reminders/ (including parser, models, database)
• geomagnetic.py
• error_analytics.py, error_handler.py, logger.py
• file_manager.py, keyboards.py, prompts_empty.py, user_management.py, utils.py
• CI/CD workflows in .github/workflows ensure automated testing and packaging.
• requirements.txt and .env-based configuration for API keys and rate limits.
Extract Insights from README
• Core components: Telegram Bot logic, Video downloader, GPT integration, Weather & recommendations, Reminders, Geomagnetic updates, Error analytics, URL shortener, Content moderation, Logging, Rate limiting.
• External dependencies: Telegram Bot API, OpenAI API, weather API, geomagnetic API, ytdl service, thecatapi, URL shortener.
• Persistence: file-based chat logs, reminder storage (likely SQLite or simple file DB).
• Scheduler: periodic tasks (weather screenshots every 6h, geomagnetic checks).
Main Components
• Telegram Client (Webhook or Long Polling)
• Bot Core (main.py + dispatcher)
• Feature Modules (each in modules/):
a. Video Downloader
b. GPT Module
c. Weather Module + Scheduler
d. Reminder Module + DB
e. Geomagnetic Module + Scheduler
f. URL Shortener & Sanitizer
g. Error Handler & Analytics
h. User Management & Moderation
• Data Stores:
• Reminder Database
• Chat Logs (file system)
• Configuration store
• External Services:
• Telegram API
• OpenAI API
• Weather API
• Geomagnetic API
• YTDL Video Service
• URL Shortener Service
• TheCatAPI
• CI/CD Pipeline (GitHub Actions)
Relationships and Interactions
• Incoming messages flow from Telegram API → Bot Core → Dispatcher → appropriate Feature Module → may read/write to Data Store → may call External Service → Bot Core → Telegram API to send response.
• Scheduled jobs in Bot Core trigger Weather & Geomagnetic Modules which call respective external APIs, store results, and may push updates to chats.
• Reminder Module schedules future notifications: user sets reminder → parser writes to Reminder DB → scheduler triggers at due time → Bot Core sends reminder message.
• Error Handler intercepts exceptions across modules, writes to log, and optionally reports to configured error channel via Telegram API.
Architectural Patterns and Design Principles
• Modular monolith: each feature encapsulated in its own module folder.
• Dispatcher pattern: routing based on message content or commands.
• Observer/scheduler for periodic tasks.
• Layered separation: Core (main, dispatcher), Modules (feature logic), Infrastructure (data, external API clients).
• Dependency injection via configuration files and environment variables.
Emphasize
• Clear component boundaries
• Data flow directions
• Inclusion of scheduled tasks and persistent storage