How karatekhd/nemesis works
Project type and purpose
• This is a Python-based, modular Telegram bot (full-stack in the sense it integrates with Telegram, a database, and exposes an internal REST API).
• Its purpose is group management/administration via plugins (“modules”), with persistence via SQLAlchemy/PostgreSQL.
File structure
• Top level:
• setup.sh, start.sh, Procfile – deployment/startup scripts (Heroku/Systemd).
• requirements.txt, runtime.txt – Python dependencies/runtime for hosting.
• tg_bot/ – the main application package.
• Inside tg_bot/:
• __main__.py – entry point (starts bot).
• sample_config.py & (optional) config.py – configuration.
• caching.py – in-memory or external cache layer.
• modules/ – plugin directory, each module implements bot commands & holds its own SQL handlers under modules/sql/.
• restapi/ – small built-in REST service (resources, models, auth).
• strings/ – i18n JSON assets.
• Infrastructure files:
• .github/workflows – CI (CodeQL).
• crowdin.yml – translation pipeline.
Key insights from README
• Bot runs on Python 3.6+, uses python-telegram-bot’s Dispatcher/Handler model.
• Modular plugin system: drop a .py under modules/ to auto-load.
• Database via SQLAlchemy (PostgreSQL).
• Two configuration modes: config.py or ENV vars (webhooks vs polling).
• Optional REST API endpoints for external integrations.
1. Telegram Platform (external)
2. Bot Application (internal):
• Entry Point (__main__.py)
• Dispatcher & Handlers
• Module Loader & Plugins
• Caching Layer
• REST API Server
• Configuration Manager
3. PostgreSQL Database (external)
4. (Optional) Webhook / Load Balancer (if using webhooks)
5. (Optional) External APIs (e.g., Google Translate)
• Telegram ↔ Bot via long polling or webhook (requests/responses).
• Bot → PostgreSQL via SQLAlchemy.
• Bot → Caching (in-memory or Redis if configured).
• Clients (or internal UIs) → Bot’s REST API → Data models → Database.
• Modules → Dispatcher (register handlers) → Telegram events.
• Modules → helper_funcs & sql submodules → database operations.
c. Architectural patterns & principles:
• Plugin architecture: loose coupling, dynamic module loading.
• Layered design: Presentation (Telegram, REST), Business (modules/dispatcher), Data (SQLAlchemy).
• Separation of concerns: caching, translation strings, config, modules, and data access isolated in their own directories.
d. Key technologies/frameworks:
• python-telegram-bot library (Dispatcher/Handler).
• SQLAlchemy ORM + PostgreSQL.
• Flask-RESTful or similar (restapi/resources & models).
• Crowdin for translation, GitHub Actions for CI.
Essential elements to capture
• Bot entrypoint and start-up (polling vs webhook).
• Dispatcher funnel into loaded modules.
• Module <→ sql helper functions <→ database cycle.
• Caching layer sitting between modules and DB (optional speed-up).
• REST API stack and how it shares models with modules.
• External API dependencies (e.g., translation services).