# karatekhd/nemesis architecture

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

- Interactive diagram: https://gitdiagram.com/karatekhd/nemesis
- Repository: https://github.com/karatekhd/nemesis

## Overview

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

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Interfaces
    subgraph "External Services"
        direction TB
        Telegram["Telegram Platform"]:::external
        GoogleAPI["Google Translate API"]:::external
        PostgreSQL[(PostgreSQL Database)]:::storage
    end

    %% Bot Core
    subgraph "Bot Application" 
        direction TB
        Entry["__main__.py (Entry Point)"]:::internal
        Config["Configuration Manager"]:::config
        Dispatcher["Dispatcher & Handlers"]:::internal
        ModuleLoader["Module Loader"]:::internal
        CacheLayer[(Caching Layer)]:::storage
        RESTServer["REST API Server"]:::internal
        Strings["i18n Strings"]:::config

        Entry -->|starts| Dispatcher
        Config -->|provides settings| Entry
        Config -->|provides settings| RESTServer
        Dispatcher -->|loads via| ModuleLoader
        ModuleLoader -->|executes| Modules
        Modules -->|query/update| CacheLayer
        Modules -->|query/update| PostgreSQL
        CacheLayer -->|writes/reads| PostgreSQL
        RESTServer -->|operates on| RESTModels
        RESTServer -->|serves| RESTResources
        RESTServer -->|auth via| RESTAuth
        RESTServer -->|uses| Config
        RESTServer -->|reads| Strings
    end

    %% Modules and Helpers
    subgraph "Modules & Helpers"
        direction TB
        subgraph "Plugins"
            direction TB
            Admin["Module: admin.py"]:::plugin
            AFK["Module: afk.py"]:::plugin
            GlobalBans["Module: global_bans.py"]:::plugin
            GoogleTransMod["Module: googletranslate.py"]:::plugin
            RestMod["Module: rest.py"]:::plugin
            OtherMods["…other modules"]:::plugin
        end
        subgraph "Helper Functions"
            direction TB
            Handlers["Dispatcher Utilities (handlers.py)"]:::internal
            HelperFuncs["General Helpers"]:::internal
        end
        subgraph "SQL Handlers"
            direction TB
            ModuleSQL["Module-specific SQL"]:::storage
        end

        ModuleLoader -->|scans| Plugins
        Plugins -->|use| Handlers
        Plugins -->|use| HelperFuncs
        Plugins -->|use| ModuleSQL
        GoogleTransMod -->|calls| GoogleAPI
    end

    %% REST API components
    subgraph "REST API Components"
        direction TB
        RESTAuth["Auth (auth.py)"]:::internal
        RESTModels["Models"]:::internal
        RESTResources["Resources"]:::internal
    end

    %% Connections between Bot and External
    Telegram -->|updates| Entry
    Entry -->|messages| Telegram
    RESTResources -->|DB Ops| PostgreSQL

    %% Click Events
    click Entry "https://github.com/karatekhd/nemesis/blob/master/tg_bot/__main__.py"
    click Config "https://github.com/karatekhd/nemesis/blob/master/tg_bot/sample_config.py"
    click CacheLayer "https://github.com/karatekhd/nemesis/blob/master/tg_bot/caching.py"
    click ModuleLoader "https://github.com/karatekhd/nemesis/tree/master/tg_bot/modules/"
    click Admin "https://github.com/karatekhd/nemesis/blob/master/tg_bot/modules/admin.py"
    click AFK "https://github.com/karatekhd/nemesis/blob/master/tg_bot/modules/afk.py"
    click GlobalBans "https://github.com/karatekhd/nemesis/blob/master/tg_bot/modules/global_bans.py"
    click GoogleTransMod "https://github.com/karatekhd/nemesis/blob/master/tg_bot/modules/googletranslate.py"
    click RestMod "https://github.com/karatekhd/nemesis/blob/master/tg_bot/modules/rest.py"
    click HelperFuncs "https://github.com/karatekhd/nemesis/tree/master/tg_bot/modules/helper_funcs/"
    click ModuleSQL "https://github.com/karatekhd/nemesis/tree/master/tg_bot/modules/sql/"
    click Handlers "https://github.com/karatekhd/nemesis/blob/master/tg_bot/modules/helper_funcs/handlers.py"
    click RESTServer "https://github.com/karatekhd/nemesis/blob/master/tg_bot/restapi/__init__.py"
    click RESTAuth "https://github.com/karatekhd/nemesis/blob/master/tg_bot/restapi/auth.py"
    click RESTModels "https://github.com/karatekhd/nemesis/tree/master/tg_bot/restapi/models/"
    click RESTResources "https://github.com/karatekhd/nemesis/tree/master/tg_bot/restapi/resources/"
    click Strings "https://github.com/karatekhd/nemesis/tree/master/tg_bot/strings/"

    %% Styles
    classDef external fill:#ffdddd,stroke:#cc0000,color:#000;
    classDef internal fill:#ddf,stroke:#006, color:#000;
    classDef storage fill:#dfd,stroke:#060, color:#000;
    classDef config fill:#ffd,stroke:#aa0, color:#000;
    classDef plugin fill:#fdf0dd,stroke:#a60, color:#000;
```
