How edm115/unzip-bot works
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)