# harmish77/jisshu-filter-bot architecture

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

- Interactive diagram: https://gitdiagram.com/harmish77/jisshu-filter-bot
- Repository: https://github.com/harmish77/jisshu-filter-bot

## Overview

##### Project Type and Purpose
- This is a **backend‑focused** Telegram Bot application with a lightweight HTTP server for indexing features.
- It consumes the Telegram API, processes commands via plugin modules, persists state in MongoDB, renders occasional HTML templates, and is packaged for deployment (Docker, Heroku, Render, VPS).

##### File Structure
- **Entry Points**
- `bot.py` – main Telegram Bot runner
- `app.py` – lightweight HTTP server for “index”/web views
- `Script.py` – auxiliary scripts (e.g., DB migrations or cron tasks)
- **Core Package**
- `Jisshu/` – internal libraries
– `bot/` – Telegram client wrapper (`clients.py`)
– `server/` – request handling logic for HTTP server
– `template/` – Jinja2 HTML templates (`dl.html`, `req.html`)
– `util/` – helper modules (config parser, file size, human‑readable formats, keepalive, template rendering, etc.)
- **Plugins** (`plugins/`)
– Each command or feature (e.g., `broadcast.py`, `pm_filter.py`, `Top.py`, Extra features) lives here.
– Loaded dynamically by the bot core.
- **Database Layer** (`database/`)
– Collections management (e.g., `users_chats_db.py`, `jsreferdb.py`, `topdb.py`, `ia_filterdb.py`)
– Exposed via a shared MongoDB client.
- **Config & Deployment**
– `info.py`, environment variables, `Procfile`, `Dockerfile`, `heroku.yml`, `runtime.txt`, `requirements.txt`

##### README for Insights
- Bot Features: streaming, download, filtering, premium management, auto‑delete, welcome messages, subscription enforcement, index pages.
- Dependencies: Python, MongoDB, Jinja2, any Telegram client library (Pyrogram/Telethon).
- Deployment targets: Heroku, Koyeb, Render, VPS, Docker.

##### Main Components & Their Interactions
a. **Telegram API (External Service)**
– Receives updates (messages, commands)
– Bot responds via API calls
b. **Bot Core**
– `bot.py` uses client wrapper (`Jisshu/bot/clients.py`)
– Dispatches incoming updates to the **Plugin Manager**
c. **Plugin Manager & Plugins**
– Dynamically loads modules from `plugins/`
– Each plugin defines handlers for commands or message patterns
– Makes calls to utility modules and database
d. **Utilities Layer**
– Shared logic: parsing configs, formatting sizes/dates, rendering templates, shortener integrations, keeping the bot alive
e. **Database (MongoDB)**
– Central persistence for users, chats, index data, stats, premium codes, top/trending
– Accessed via `database/` modules
f. **HTTP Server**
– `app.py` and `Jisshu/server/` handle inbound HTTP requests (e.g., `/index`)
– Renders templates from `Jisshu/template/` using Jinja2 and data from MongoDB
g. **External APIs & Services**
– IMDb API, custom shorteners, streaming & download providers
– Logging channel (Telegram) for operational logs
h. **Deployment Environment**
– Docker container or direct Python runtime
– Environment variables injected via Heroku, Render, Koyeb, or VPS
– `Dockerfile`, `Procfile`, `heroku.yml`, `runtime.txt`

##### Architectural Patterns & Design Principles
- **Modular Plugin Architecture** – each feature is isolated in its own module, enabling easy extension.
- **Layered Structure** – clear separation between transport (Telegram / HTTP), business logic (plugins), utilities, and data access.
- **Template‑View Pattern** – HTTP server uses Jinja2 templates to render HTML views.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Services
    subgraph "External Services"
        TELE["Telegram API"]:::external
        IMDB["IMDb API"]:::external
        SHORT["Shortener APIs"]:::external
        LOGS["Telegram Logging Channel"]:::external
    end

    %% Entry Points
    subgraph "Entry Points"
        BOTPY["bot.py"]:::core
        click BOTPY "https://github.com/harmish77/jisshu-filter-bot/blob/main/bot.py"
        APPPY["app.py"]:::core
        click APPPY "https://github.com/harmish77/jisshu-filter-bot/blob/main/app.py"
        SCRIPTPY["Script.py"]:::core
        click SCRIPTPY "https://github.com/harmish77/jisshu-filter-bot/blob/main/Script.py"
    end

    %% Bot Core
    subgraph "Bot Core"
        CLIENTS["clients.py"]:::core
        click CLIENTS "https://github.com/harmish77/jisshu-filter-bot/blob/main/Jisshu/bot/clients.py"
        BOTDIR["Jisshu/bot/"]:::core
        click BOTDIR "https://github.com/harmish77/jisshu-filter-bot/tree/main/Jisshu/bot/"
    end

    %% Plugin Manager & Plugins
    subgraph "Plugin Manager & Plugins"
        PLUGMAN["plugins/"]:::core
        click PLUGMAN "https://github.com/harmish77/jisshu-filter-bot/tree/main/plugins/"
        BROAD["broadcast.py"]:::core
        click BROAD "https://github.com/harmish77/jisshu-filter-bot/blob/main/plugins/broadcast.py"
        PMF["pm_filter.py"]:::core
        click PMF "https://github.com/harmish77/jisshu-filter-bot/blob/main/plugins/pm_filter.py"
        TOPP["Top.py"]:::core
        click TOPP "https://github.com/harmish77/jisshu-filter-bot/blob/main/plugins/Top.py"
        JOIN["join_req.py"]:::core
        click JOIN "https://github.com/harmish77/jisshu-filter-bot/blob/main/plugins/join_req.py"
        INDEX["index.py"]:::core
        click INDEX "https://github.com/harmish77/jisshu-filter-bot/blob/main/plugins/index.py"
        HELP["plugins/helper/"]:::core
        click HELP "https://github.com/harmish77/jisshu-filter-bot/tree/main/plugins/helper/"
        EXTRA["plugins/Extra/"]:::core
        click EXTRA "https://github.com/harmish77/jisshu-filter-bot/tree/main/plugins/Extra/"
    end

    %% Utilities
    subgraph "Utilities"
        UTILDIR["Jisshu/util/"]:::util
        click UTILDIR "https://github.com/harmish77/jisshu-filter-bot/tree/main/Jisshu/util/"
        CP["config_parser.py"]:::util
        click CP "https://github.com/harmish77/jisshu-filter-bot/blob/main/Jisshu/util/config_parser.py"
        CDL["custom_dl.py"]:::util
        click CDL "https://github.com/harmish77/jisshu-filter-bot/blob/main/Jisshu/util/custom_dl.py"
        FP["file_properties.py"]:::util
        click FP "https://github.com/harmish77/jisshu-filter-bot/blob/main/Jisshu/util/file_properties.py"
        FSZ["file_size.py"]:::util
        click FSZ "https://github.com/harmish77/jisshu-filter-bot/blob/main/Jisshu/util/file_size.py"
        HR["human_readable.py"]:::util
        click HR "https://github.com/harmish77/jisshu-filter-bot/blob/main/Jisshu/util/human_readable.py"
        KA["keepalive.py"]:::util
        click KA "https://github.com/harmish77/jisshu-filter-bot/blob/main/Jisshu/util/keepalive.py"
        RT["render_template.py"]:::util
        click RT "https://github.com/harmish77/jisshu-filter-bot/blob/main/Jisshu/util/render_template.py"
        TF["time_format.py"]:::util
        click TF "https://github.com/harmish77/jisshu-filter-bot/blob/main/Jisshu/util/time_format.py"
    end

    %% Database Layer
    subgraph "Database Layer"
        DATABASE[(MongoDB)]:::data
        DBDIR["database/"]:::data
        click DBDIR "https://github.com/harmish77/jisshu-filter-bot/tree/main/database/"
        USERS["users_chats_db.py"]:::data
        click USERS "https://github.com/harmish77/jisshu-filter-bot/blob/main/database/users_chats_db.py"
        JSREF["jsreferdb.py"]:::data
        click JSREF "https://github.com/harmish77/jisshu-filter-bot/blob/main/database/jsreferdb.py"
        TOPDB["topdb.py"]:::data
        click TOPDB "https://github.com/harmish77/jisshu-filter-bot/blob/main/database/topdb.py"
        IA["ia_filterdb.py"]:::data
        click IA "https://github.com/harmish77/jisshu-filter-bot/blob/main/database/ia_filterdb.py"
        CONFDB["config_db.py"]:::data
        click CONFDB "https://github.com/harmish77/jisshu-filter-bot/blob/main/database/config_db.py"
    end

    %% HTTP Server
    subgraph "HTTP Server"
        SERVERAPP["app.py"]:::server
        click SERVERAPP "https://github.com/harmish77/jisshu-filter-bot/blob/main/app.py"
        SERVLOGIC["Jisshu/server/"]:::server
        click SERVLOGIC "https://github.com/harmish77/jisshu-filter-bot/blob/main/Jisshu/server/exceptions.py"
        TEMPLATEDIR["Jisshu/template/"]:::server
        click TEMPLATEDIR "https://github.com/harmish77/jisshu-filter-bot/tree/main/Jisshu/template/"
        DL["dl.html"]:::server
        click DL "https://github.com/harmish77/jisshu-filter-bot/blob/main/Jisshu/template/dl.html"
        REQHTML["req.html"]:::server
        click REQHTML "https://github.com/harmish77/jisshu-filter-bot/blob/main/Jisshu/template/req.html"
    end

    %% Deployment
    subgraph "Deployment & Config"
        DOCKER["Dockerfile"]:::deploy
        click DOCKER "https://github.com/harmish77/jisshu-filter-bot/tree/main/Dockerfile"
        PROC["Procfile"]:::deploy
        click PROC "https://github.com/harmish77/jisshu-filter-bot/tree/main/Procfile"
        HEROKU["heroku.yml"]:::deploy
        click HEROKU "https://github.com/harmish77/jisshu-filter-bot/blob/main/heroku.yml"
        RUNTIME["runtime.txt"]:::deploy
        click RUNTIME "https://github.com/harmish77/jisshu-filter-bot/blob/main/runtime.txt"
        REQTXT["requirements.txt"]:::deploy
        click REQTXT "https://github.com/harmish77/jisshu-filter-bot/blob/main/requirements.txt"
        LOGCONF["logging.conf"]:::deploy
        click LOGCONF "https://github.com/harmish77/jisshu-filter-bot/blob/main/logging.conf"
        INFO["info.py"]:::deploy
        click INFO "https://github.com/harmish77/jisshu-filter-bot/blob/main/info.py"
        README["README.md & LICENSE"]:::deploy
        click README "https://github.com/harmish77/jisshu-filter-bot/blob/main/README.md"
    end

    %% Connections
    TELE --> BOTPY
    BOTPY --> CLIENTS
    CLIENTS --> PLUGMAN
    PLUGMAN --> BROAD
    PLUGMAN --> PMF
    PLUGMAN --> TOPP
    PLUGMAN --> JOIN
    PLUGMAN --> INDEX
    PLUGMAN --> DATABASE
    PLUGMAN --> UTILDIR
    PLUGMAN --> IMDB
    PLUGMAN --> SHORT
    PLUGMAN --> LOGS

    UTILDIR --> CP
    UTILDIR --> CDL
    UTILDIR --> FP
    UTILDIR --> FSZ
    UTILDIR --> HR
    UTILDIR --> KA
    UTILDIR --> RT
    UTILDIR --> TF

    DATABASE --> USERS
    DATABASE --> JSREF
    DATABASE --> TOPDB
    DATABASE --> IA
    DATABASE --> CONFDB

    APPPY --> SERVLOGIC
    SERVLOGIC --> DATABASE
    SERVLOGIC --> TEMPLATEDIR
    TEMPLATEDIR --> DL
    TEMPLATEDIR --> REQHTML
    SERVLOGIC --> RT

    %% Deployment links
    BOTPY --> DOCKER
    APPPY --> DOCKER
    SCRIPTPY --> DOCKER
    UTILDIR --> DOCKER
    DBDIR --> DOCKER
    SERVLOGIC --> DOCKER

    %% Styles
    classDef external fill:#D0E8FF,stroke:#3B82F6,color:#1E3A8A;
    classDef core fill:#D1FAE5,stroke:#10B981,color:#065F46;
    classDef util fill:#F3F4F6,stroke:#9CA3AF,color:#374151;
    classDef data fill:#FEF3C7,stroke:#F59E0B,color:#92400E;
    classDef server fill:#E0F2FE,stroke:#60A5FA,color:#1E3A8A;
    classDef deploy fill:#F5F3FF,stroke:#A78BFA,color:#4C1D95;
```
