# fox-io/hydrus_telegram_bot architecture

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

- Interactive diagram: https://gitdiagram.com/fox-io/hydrus_telegram_bot
- Repository: https://github.com/fox-io/hydrus_telegram_bot

## Overview

##### Project Type and Purpose
- This is a backend automation service (“bot”) that:
- Reads configuration (config/config.json)
- Periodically queries the Hydrus Network client for images tagged to be posted
- Downloads/processes those images
- Posts them to a Telegram channel via the Bot API
- Updates the tags in Hydrus once posting is complete

a. Core Bot Application (bot.py)
b. Configuration Layer
– Config Manager module (modules/config_manager.py) reads config/config.json
c. Scheduling Layer
– Schedule Manager (modules/schedule_manager.py) triggers posting at configured intervals
d. Queue Management
– Queue Manager (modules/queue_manager.py) handles in-memory or on-disk queue of image tasks
– Local Queue Storage (queue/QUEUED_IMAGES folder)
e. Hydrus Integration
– Hydrus Manager (modules/hydrus_manager.py) calls the Hydrus Client API
f. File & Media Processing
– File Manager (modules/file_manager.py) downloads images, invokes ImageMagick/Wand or ffmpeg as needed
g. Telegram Integration
– Telegram Manager (modules/telegram_manager.py) calls the Telegram Bot API to post images
h. Logging
– Log Manager (modules/log_manager.py) writes logs to console/files

1. At startup, Core Bot reads config.json through Config Manager.
2. Schedule Manager → triggers every N minutes (time configured).
3. On trigger, Schedule Manager → Queue Manager to enqueue work.
4. Queue Manager → Hydrus Manager: “give me all images tagged with queue_tag.”
5. Hydrus Manager ↔ Hydrus API (HTTP calls) → returns metadata + file URLs.
6. Queue Manager stores tasks in Local Queue Storage.
7. Worker loop:
a. Queue Manager → File Manager: “download this image.”
b. File Manager ↔ Hydrus API (file download) → writes file locally.
c. File Manager → (optionally) ffmpeg/ImageMagick for resizing/format conversion.
d. File Manager → Telegram Manager: “post this file + metadata.”
e. Telegram Manager ↔ Telegram API → posts to channel.
f. On success, Telegram Manager → Hydrus Manager: “update tags (remove queue_tag, add posted_tag).”
8. Throughout all steps, modules call Log Manager to record events and errors.

##### Architectural Patterns & Principles
- Modularity: Each “manager” module has a single responsibility.
- Layering: Config → Scheduling → Queue → Integration → External Services
- Separation of concerns: Keeps API-specific logic (Hydrus, Telegram) out of scheduling and file logic.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Bot Application Container
    subgraph "Bot Application"
        direction TB
        Bot["Core Bot Application\n(bot.py)"]:::internal
        ConfigMgr["Config Manager\n(modules/config_manager.py)"]:::internal
        ScheduleMgr["Schedule Manager\n(modules/schedule_manager.py)"]:::internal
        QueueMgr["Queue Manager\n(modules/queue_manager.py)"]:::internal
        HydrusMgr["Hydrus Manager\n(modules/hydrus_manager.py)"]:::internal
        FileMgr["File Manager\n(modules/file_manager.py)"]:::internal
        TelegramMgr["Telegram Manager\n(modules/telegram_manager.py)"]:::internal
        LogMgr["Log Manager\n(modules/log_manager.py)"]:::internal
        ConfigFile["Configuration File\n(config/config.json.example)"]:::storage
        QueueStorage["Local Queue Storage\n(queue/QUEUED_IMAGES)"]:::storage
    end

    %% External Services
    HydrusAPI["Hydrus Network Client API"]:::external
    TelegramAPI["Telegram Bot API"]:::external
    MediaTools["ImageMagick & ffmpeg Tools"]:::external

    %% Data Flows
    Bot -->|reads config| ConfigMgr
    ConfigMgr -->|loads JSON| ConfigFile
    Bot --> ScheduleMgr
    ScheduleMgr -->|trigger every N minutes| QueueMgr

    QueueMgr -->|enqueue tasks| QueueStorage
    QueueMgr -->|request images| HydrusMgr
    HydrusMgr -->|GET /api/get_files| HydrusAPI
    HydrusAPI -->|metadata & URLs| HydrusMgr
    HydrusMgr --> QueueMgr

    QueueMgr -->|dequeue task| FileMgr
    FileMgr -->|download image| HydrusAPI
    HydrusAPI -->|file stream| FileMgr
    FileMgr -->|process media| MediaTools
    MediaTools --> FileMgr
    FileMgr -->|post image + metadata| TelegramMgr
    TelegramMgr -->|POST /bot/sendPhoto| TelegramAPI
    TelegramAPI -->|response| TelegramMgr
    TelegramMgr -->|update tags| HydrusMgr
    HydrusMgr -->|POST /api/edit_tags| HydrusAPI

    %% Logging
    ConfigMgr -->|logs events| LogMgr
    ScheduleMgr -->|logs events| LogMgr
    QueueMgr -->|logs events| LogMgr
    HydrusMgr -->|logs events| LogMgr
    FileMgr -->|logs events| LogMgr
    TelegramMgr -->|logs events| LogMgr

    %% Click Events
    click Bot "https://github.com/fox-io/hydrus_telegram_bot/blob/master/bot.py"
    click ConfigMgr "https://github.com/fox-io/hydrus_telegram_bot/blob/master/modules/config_manager.py"
    click ConfigFile "https://github.com/fox-io/hydrus_telegram_bot/blob/master/config/config.json.example"
    click ScheduleMgr "https://github.com/fox-io/hydrus_telegram_bot/blob/master/modules/schedule_manager.py"
    click QueueMgr "https://github.com/fox-io/hydrus_telegram_bot/blob/master/modules/queue_manager.py"
    click QueueStorage "https://github.com/fox-io/hydrus_telegram_bot/tree/master/queue/QUEUED_IMAGES"
    click HydrusMgr "https://github.com/fox-io/hydrus_telegram_bot/blob/master/modules/hydrus_manager.py"
    click FileMgr "https://github.com/fox-io/hydrus_telegram_bot/blob/master/modules/file_manager.py"
    click TelegramMgr "https://github.com/fox-io/hydrus_telegram_bot/blob/master/modules/telegram_manager.py"
    click LogMgr "https://github.com/fox-io/hydrus_telegram_bot/blob/master/modules/log_manager.py"

    %% Styles
    classDef internal fill:#bbdefb,stroke:#1e88e5,color:#0d47a1;
    classDef external fill:#ffe082,stroke:#ffa000,color:#e65100;
    classDef storage  fill:#c8e6c9,stroke:#388e3c,color:#1b5e20;
```
