# edm115/unzip-bot architecture

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

- Interactive diagram: https://gitdiagram.com/edm115/unzip-bot
- Repository: https://github.com/edm115/unzip-bot

## Overview

##### Project type and purpose
- This is a single-codebase, Python-based Telegram bot (“unzip-bot”) that automates downloading, extracting, and re-uploading archives for end users.
- It uses the Telegram Bot API for messaging, MongoDB for persistence, local volumes for storage (Downloaded/Thumbnails), and external unarchiving tools (unrar, tar, etc.). It’s deployed in Docker or Heroku, with CI/CD via GitHub Actions.

##### File structure
- Top-level files
- Dockerfile, start.sh, install_unrar.sh – Docker build and runtime scripts
- config.py, .env – configuration loader
- pyproject.toml, uv.lock – Python packaging and lock files
- Procfile, app.json, heroku.yml – Heroku deployment descriptors
- .github/workflows – CI/CD pipelines for code style, build, security
- Core application directory: unzipbot/
- __main__.py – entry point (invokes start.py)
- helpers/ – support modules
– database.py: MongoDB interaction
– start.py: bot initialization & dispatcher setup
– unzip_help.py: orchestrates calls to external archive tools
- i18n/ – localization strings for messages and buttons
- modules/ – bot logic separated by responsibility
– commands.py: handles /commands (start, help, mode, etc.)
– callbacks.py: inline-keyboard button callbacks
– ext_script/: wrappers around external scripts (custom thumbnail, metadata, upload helper)
- Configs & scripts for environment, deployments, CI/CD.

##### README for additional insights
- Describes features (archive types, password, split archives, download links, custom thumbnail, upload modes).
- Admin features (broadcast, ban/unban, stats, eval/exec, logs).
- Deployment instructions (Heroku, Docker, volumes for Downloaded & Thumbnails).

##### Main components
a. Telegram HTTP/Webhook or Long-polling Layer
– Shows incoming updates & outgoing messages/files
b. Bot Application (Docker Container)
– Entry point (start.py)
– Dispatcher & Routing (commands.py, callbacks.py)
– Internationalization (i18n/)
– Helpers: database.py → MongoDB client; unzip_help.py → external archive CLI wrappers; ext_script helpers
c. External Services
– MongoDB cluster (MONGODB_URL)
– External archive tools (unrar, unzip, 7z kernels in the container)
– Telegram Bot API (external)
– Logging channel (Telegram Group/Channel via BOT_TOKEN)
d. Persistent Storage Volumes
– /app/Downloaded volume
– /app/Thumbnails volume
e. CI/CD & Deployment
– GitHub Actions workflows (build, lint, security)
– Docker Hub registry
– Heroku remote (Procfile, app.json)

##### Relationships and interactions
- Telegram → Bot Container: receives Update payloads
- Bot Container → MongoDB: reads/writes user/session data, admin settings
- Bot Container → File System volume: writes downloaded archives, extracted files, custom thumbnails
- Bot Container → External CLI tools: invokes unzip/rar commands via subprocess in unzip_help.py
- Bot Container → Telegram: sends back extracted files / thumbnails / messages
- CI/CD triggers: pushes to GitHub → GitHub Actions build & push Docker image → Docker Hub → Heroku deploy

##### Architectural patterns and design principles
- Modular separation: helpers vs. modules (command vs. callback handlers)
- Single-responsibility: ext_script wrappers isolate metadata/thumbnail logic
- Environment-driven configuration (.env, config.py)
- Layered I/O: API layer (Telegram) → business logic (modules) → data layer (MongoDB & FS)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Services
    TelegramAPI["Telegram Bot API"]:::external
    MongoDB["MongoDB Cluster"]:::external
    DockerHub["Docker Hub Registry"]:::external
    GitHubActions["GitHub Actions"]:::external
    HerokuDyno["Heroku Dyno"]:::external

    %% Container grouping
    subgraph "Bot Container" 
        direction TB
        %% Entry & Initialization
        Main["__main__.py"]:::internal
        Start["start.py"]:::internal

        %% Dispatcher & Routing
        Commands["commands.py"]:::internal
        Callbacks["callbacks.py"]:::internal

        %% Internationalization
        Buttons["buttons.py"]:::internal
        Messages["messages.py"]:::internal
        LangEN["en.json"]:::internal

        %% Helpers
        Database["database.py"]:::internal
        UnzipHelp["unzip_help.py"]:::internal

        %% External CLI Tools
        CLI["External CLI Tools (unrar, tar, 7z)"]:::cli

        %% Volumes
        Downloaded["/app/Downloaded"]:::volume
        Thumbnails["/app/Thumbnails"]:::volume

        %% Config
        ConfigFile["config.py"]:::internal
        EnvFile[".env"]:::internal

        %% Ext Script Helpers
        CustomThumb["custom_thumbnail.py"]:::internal
        MetadataHelper["metadata_helper.py"]:::internal
        UpHelper["up_helper.py"]:::internal
        ExtHelper["ext_helper.py"]:::internal

        %% Docker & Runtime Scripts
        Dockerfile["Dockerfile"]:::internal
        InstallUnrar["install_unrar.sh"]:::internal
        StartSh["start.sh"]:::internal

        %% Deployment Descriptors
        Procfile["Procfile"]:::internal
        AppJson["app.json"]:::internal
        HerokuYml["heroku.yml"]:::internal

        %% CI/CD Workflows
        Workflows[".github/workflows"]:::internal

        %% Internal Relationships
        Main --> Start
        Start --> Commands
        Start --> Callbacks
        Commands -->|uses i18n| Buttons
        Commands -->|uses i18n| Messages
        Commands -->|loads lang| LangEN
        Callbacks -->|uses i18n| Buttons
        Callbacks -->|uses i18n| Messages
        Database --> MongoDB
        Commands --> Database
        Callbacks --> Database
        Commands --> UnzipHelp
        UnzipHelp --> CLI
        UnzipHelp --> Downloaded
        UnzipHelp --> Thumbnails
        Commands -->|reads config| ConfigFile
        Commands -->|reads env| EnvFile

        %% File watchers and runtime scripts
        Dockerfile --> InstallUnrar
        Dockerfile --> StartSh
        Procfile --> AppJson
        Procfile --> HerokuYml

    end

    %% External interactions
    TelegramAPI -->|updates| Main
    Main -->|sends/receives| TelegramAPI
    BotContainerEnd(( )):::internal
    Downloaded -->|persist files| Thumbnails

    %% CI/CD & Deployment Flow
    GitHubActions -->|build & test| DockerHub
    DockerHub -->|deploy image| HerokuDyno
    HerokuDyno --> TelegramAPI

    %% Click Events
    click Main "https://github.com/edm115/unzip-bot/blob/v7/unzipbot/__main__.py"
    click Start "https://github.com/edm115/unzip-bot/blob/v7/unzipbot/helpers/start.py"
    click Commands "https://github.com/edm115/unzip-bot/blob/v7/unzipbot/modules/commands.py"
    click Callbacks "https://github.com/edm115/unzip-bot/blob/v7/unzipbot/modules/callbacks.py"
    click Buttons "https://github.com/edm115/unzip-bot/blob/v7/unzipbot/i18n/buttons.py"
    click Messages "https://github.com/edm115/unzip-bot/blob/v7/unzipbot/i18n/messages.py"
    click LangEN "https://github.com/edm115/unzip-bot/blob/v7/unzipbot/i18n/lang/en.json"
    click Database "https://github.com/edm115/unzip-bot/blob/v7/unzipbot/helpers/database.py"
    click UnzipHelp "https://github.com/edm115/unzip-bot/blob/v7/unzipbot/helpers/unzip_help.py"
    click CustomThumb "https://github.com/edm115/unzip-bot/blob/v7/unzipbot/modules/ext_script/custom_thumbnail.py"
    click MetadataHelper "https://github.com/edm115/unzip-bot/blob/v7/unzipbot/modules/ext_script/metadata_helper.py"
    click UpHelper "https://github.com/edm115/unzip-bot/blob/v7/unzipbot/modules/ext_script/up_helper.py"
    click ExtHelper "https://github.com/edm115/unzip-bot/blob/v7/unzipbot/modules/ext_script/ext_helper.py"
    click ConfigFile "https://github.com/edm115/unzip-bot/blob/v7/config.py"
    click EnvFile "https://github.com/edm115/unzip-bot/blob/v7/.env"
    click Dockerfile "https://github.com/edm115/unzip-bot/tree/v7/Dockerfile"
    click InstallUnrar "https://github.com/edm115/unzip-bot/blob/v7/install_unrar.sh"
    click StartSh "https://github.com/edm115/unzip-bot/blob/v7/start.sh"
    click Procfile "https://github.com/edm115/unzip-bot/tree/v7/Procfile"
    click AppJson "https://github.com/edm115/unzip-bot/blob/v7/app.json"
    click HerokuYml "https://github.com/edm115/unzip-bot/blob/v7/heroku.yml"
    click Workflows "https://github.com/edm115/unzip-bot/tree/v7/.github/workflows/"

    %% Styles
    classDef external fill:#b2f2bb,stroke:#0f5132;
    classDef internal fill:#d0ebff,stroke:#1864ab;
    classDef volume fill:#fff3bf,stroke:#704214;
    classDef cli fill:#e9ecef,stroke:#495057;
```
