# vo1dee/psychochauffeurbot architecture

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

- Interactive diagram: https://gitdiagram.com/vo1dee/psychochauffeurbot
- Repository: https://github.com/vo1dee/psychochauffeurbot

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User and entry
    User["User"] -->|"sends message"| TelegramAPI["Telegram API"]:::external
    TelegramAPI -->|"webhook/long-poll"| BotCore["Bot Core\n(main.py + Dispatcher)"]:::core

    %% Configuration
    subgraph "Configuration Stores"
        ConfigGroup["Group Chats Config"]:::core
        ConfigPrivate["Private Chats Config"]:::core
    end
    BotCore -->|"load configs"| ConfigGroup
    BotCore -->|"load configs"| ConfigPrivate

    %% Feature Modules
    subgraph "Feature Modules" 
        Video["Video Downloader"]:::core
        GPT["GPT Integration"]:::core
        Weather["Weather Module"]:::core
        Geom["Geomagnetic Module"]:::core
        Reminders["Reminder Module"]:::core
        Utils["URL Utilities & Sanitizer"]:::core
        ErrorHandler["Error Handler"]:::core
        ErrorAnalytics["Error Analytics"]:::core
        Logger["Logger"]:::core
        UserMgmt["User Management & Moderation"]:::core
        Keyboards["Keyboards (UI Layer)"]:::core
        FileManager["File Management"]:::core
        Diagnostics["Diagnostics"]:::core
        APIDiag["API Health Checks"]:::core
    end

    BotCore -->|"dispatch to"| Video
    BotCore -->|"dispatch to"| GPT
    BotCore -->|"dispatch to"| Weather
    BotCore -->|"dispatch to"| Geom
    BotCore -->|"dispatch to"| Reminders
    BotCore -->|"dispatch to"| Utils
    BotCore -->|"dispatch to"| ErrorHandler
    BotCore -->|"dispatch to"| ErrorAnalytics
    BotCore -->|"dispatch to"| Logger
    BotCore -->|"dispatch to"| UserMgmt
    BotCore -->|"dispatch to"| Keyboards
    BotCore -->|"dispatch to"| FileManager
    BotCore -->|"dispatch to"| Diagnostics
    BotCore -->|"dispatch to"| APIDiag

    %% Data Stores
    subgraph "Persistent Data Stores"
        RemDB["Reminder Database"]:::data
        ChatLogs["Chat Logs (FS)"]:::data
        ConfigStore["Configuration Store"]:::data
    end
    Reminders -->|"read/write"| RemDB
    Reminders -->|"parse"| RemDB
    Logger -->|"write logs"| ChatLogs
    BotCore -->|"read configs"| ConfigStore

    %% Scheduler
    Scheduler["Scheduler"]:::core
    BotCore --> Scheduler
    Scheduler -->|"trigger every 6h"| Weather
    Scheduler -->|"trigger periodic"| Geom
    Scheduler -->|"trigger reminders"| Reminders

    %% External Services
    subgraph "External Services"
        OpenAI["OpenAI API"]:::external
        YTDL["YTDL Video Service"]:::external
        WeatherAPI["OpenWeather API"]:::external
        GeomAPI["Geomagnetic API"]:::external
        Shortener["URL Shortener Service"]:::external
        CatAPI["TheCatAPI"]:::external
        TelegramAPI
    end
    Video -->|"download via HTTP"| YTDL
    GPT -->|"HTTP request"| OpenAI
    Weather -->|"HTTP request"| WeatherAPI
    Geom -->|"HTTP request"| GeomAPI
    Utils -->|"sanitize URL"| Shortener
    Utils -->|"cat image"| CatAPI
    ErrorHandler -->|"report error"| TelegramAPI

    %% Response flow
    Video --> BotCore
    GPT --> BotCore
    Weather --> BotCore
    Geom --> BotCore
    Reminders --> BotCore
    Utils --> BotCore
    BotCore -->|"send response"| TelegramAPI
    TelegramAPI --> User

    %% CI/CD and Tests
    subgraph "CI/CD & Testing"
        CI["GitHub Actions"]:::ci
        Tests["Automated Tests Suite"]:::ci
    end
    CI -->|"runs tests"| Tests
    CI -->|"deploy bot"| BotCore

    %% Click Events
    click BotCore "https://github.com/vo1dee/psychochauffeurbot/blob/main/main.py"
    click ConfigGroup "https://github.com/vo1dee/psychochauffeurbot/tree/main/config/group_chats/"
    click ConfigPrivate "https://github.com/vo1dee/psychochauffeurbot/tree/main/config/private_chats/"
    click Video "https://github.com/vo1dee/psychochauffeurbot/blob/main/modules/video_downloader.py"
    click GPT "https://github.com/vo1dee/psychochauffeurbot/blob/main/modules/gpt.py"
    click Weather "https://github.com/vo1dee/psychochauffeurbot/blob/main/modules/weather.py"
    click Geom "https://github.com/vo1dee/psychochauffeurbot/blob/main/modules/geomagnetic.py"
    click Reminders "https://github.com/vo1dee/psychochauffeurbot/blob/main/modules/reminders/reminders.py"
    click RemDB "https://github.com/vo1dee/psychochauffeurbot/blob/main/modules/reminders/reminder_db.py"
    click RemModels "https://github.com/vo1dee/psychochauffeurbot/blob/main/modules/reminders/reminder_models.py"
    click RemParser "https://github.com/vo1dee/psychochauffeurbot/blob/main/modules/reminders/reminder_parser.py"
    click Utils "https://github.com/vo1dee/psychochauffeurbot/blob/main/modules/utils.py"
    click ErrorHandler "https://github.com/vo1dee/psychochauffeurbot/blob/main/modules/error_handler.py"
    click ErrorAnalytics "https://github.com/vo1dee/psychochauffeurbot/blob/main/modules/error_analytics.py"
    click Logger "https://github.com/vo1dee/psychochauffeurbot/blob/main/modules/logger.py"
    click UserMgmt "https://github.com/vo1dee/psychochauffeurbot/blob/main/modules/user_management.py"
    click Keyboards "https://github.com/vo1dee/psychochauffeurbot/blob/main/modules/keyboards.py"
    click FileManager "https://github.com/vo1dee/psychochauffeurbot/blob/main/modules/file_manager.py"
    click Diagnostics "https://github.com/vo1dee/psychochauffeurbot/blob/main/modules/diagnostics.py"
    click APIDiag "https://github.com/vo1dee/psychochauffeurbot/blob/main/utils/api_diagnosis.py"
    click CI "https://github.com/vo1dee/psychochauffeurbot/tree/main/.github/workflows/"
    click Tests "https://github.com/vo1dee/psychochauffeurbot/tree/main/tests/"

    %% Styles
    classDef core fill:#D6EAF8,stroke:#1B4F72
    classDef external fill:#D5F5E3,stroke:#186A3B
    classDef data fill:#FAD7A0,stroke:#B9770E
    classDef ci fill:#D5D8DC,stroke:#566573
```
