# hiifyi/vps architecture

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

- Interactive diagram: https://gitdiagram.com/hiifyi/vps
- Repository: https://github.com/hiifyi/vps

## Overview

##### Project type and purpose
- This is a Telegram‑based “filter” bot (Alexa Auto Filter Bot) written in Python. It’s purely a backend service (no user‑facing web UI) that listens to Telegram updates, processes file‑related commands, enforces subscription rules, streams/downloads content, and manages state in MongoDB.

##### File structure
- Top‑level script files:
- bot.py / main.py / Script.py – entry points that initialize the bot client and start event listeners.
- app.py – auxiliary app (possibly a lightweight web hook or keep‑alive endpoint).
- info.py – loads ENV/config variables into the application.
- Core library (“Jisshu” package):
- Jisshu/bot/clients.py – wraps the Telegram client (Pyrogram/Telethon).
- Jisshu/server – custom server or exception handlers.
- Jisshu/util – helper routines: config parsing, download logic, template rendering, time formatting, etc.
- Jisshu/template – HTML templates for logs or responses.
- database/ – MongoDB abstraction modules (one per collection: users, chats, filters, referrals, top lists).
- plugins/ – each .py file is a feature module (commands, streaming, freesub, premium, ads, etc.).
- config/deployment files: Dockerfile, heroku.yml, Procfile, requirements.txt, runtime.txt, logging.conf.

##### README for additional insights
- Confirms use of MongoDB (DATABASE_URI, DATABASE_NAME).
- Requires BOT_TOKEN, API_ID/HASH (Telegram API).
- Deployable to Heroku, Render, Koyeb, or VPS.
- No mention of microservices—everything runs in one process.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Entry Points
    subgraph "Entry Points"
        BOTPY["bot.py"]:::entry
        MAINPY["main.py"]:::entry
        SCRIPTPY["Script.py"]:::entry
        APPPY["app.py"]:::entry
    end

    %% Config Loader
    CONFIG["Configuration Loader"]:::config

    %% Core Components
    TELEGRAM["Telegram API"]:::external
    CLIENT["Bot Client"]:::core
    DISP["Dispatcher / Plugin Manager"]:::core

    %% Plugins
    subgraph "Plugins" 
        DOWNLOAD["Downloaders"]:::plugin
        PREMIUM["Premium Management"]:::plugin
        ADMIN["Admin Commands"]:::plugin
        FREESUB["FreeSub Feature"]:::plugin
    end

    %% Utilities
    subgraph "Utilities & Templates"
        subgraph "Utilities"
            CPARSER["config_parser"]:::util
            DLLOGIC["custom_dl"]:::util
            FILEPROP["file_properties"]:::util
            FILESIZE["file_size"]:::util
            HUMREAD["human_readable"]:::util
            KEEPALIVE["keepalive"]:::util
            RENDER["render_template"]:::util
            TIMEFMT["time_format"]:::util
        end
        subgraph "Templates"
            DLHTML["dl.html"]:::template
            REQHTML["req.html"]:::template
        end
    end

    %% Database Layer
    subgraph "Database (MongoDB)"
        CONFIGDB["config_db"]:::db
        FILTERDB["ia_filterdb"]:::db
        REFERDB["jsreferdb"]:::db
        TOPDB["topdb"]:::db
        USRCHATDB["users_chats_db"]:::db
    end

    %% External Services
    subgraph "External Services"
        IMDB["IMDB API"]:::external
        STREAMSRC["Stream Sources"]:::external
        SHORTENER["URL Shortener"]:::external
    end

    %% Logging
    LOGGER["Logger / LOG_CHANNEL"]:::log

    %% Startup Flow
    BOTPY -->|startup| CONFIG
    MAINPY -->|startup| CONFIG
    SCRIPTPY -->|startup| CONFIG
    APPPY -->|startup| CONFIG
    CONFIG -->|loads ENV| CPARSER

    %% Main Flow
    TELEGRAM -->|1 Receive Update| CLIENT
    CLIENT -->|2 Dispatch Update| DISP
    DISP -->|3 invoke feature| DOWNLOAD & PREMIUM & ADMIN & FREESUB
    DOWNLOAD & PREMIUM & ADMIN & FREESUB -->|4 read/write state| CONFIGDB & FILTERDB & REFERDB & TOPDB & USRCHATDB
    DOWNLOAD & PREMIUM & ADMIN & FREESUB -->|5 call external| IMDB & STREAMSRC & SHORTENER
    DOWNLOAD & PREMIUM & ADMIN & FREESUB -->|6 format output| RENDER & HUMREAD & TIMEFMT & FILESIZE & FILEPROP
    RENDER -->|7 template| DLHTML & REQHTML
    DOWNLOAD & PREMIUM & ADMIN & FREESUB -->|8 send response| CLIENT
    CLIENT -->|9 Send Response| TELEGRAM

    %% Logging
    DOWNLOAD & PREMIUM & ADMIN & FREESUB -->|log events| LOGGER
    CLIENT -->|log events| LOGGER

    %% Click Events
    click CLIENT "https://github.com/hiifyi/vps/blob/main/Jisshu/bot/clients.py"
    click DISP "https://github.com/hiifyi/vps/tree/main/plugins/"
    click DOWNLOAD "https://github.com/hiifyi/vps/tree/main/plugins/"
    click PREMIUM "https://github.com/hiifyi/vps/tree/main/plugins/"
    click ADMIN "https://github.com/hiifyi/vps/tree/main/plugins/"
    click FREESUB "https://github.com/hiifyi/vps/tree/main/plugins/"
    click CPARSER "https://github.com/hiifyi/vps/blob/main/Jisshu/util/config_parser.py"
    click DLLOGIC "https://github.com/hiifyi/vps/blob/main/Jisshu/util/custom_dl.py"
    click FILEPROP "https://github.com/hiifyi/vps/blob/main/Jisshu/util/file_properties.py"
    click FILESIZE "https://github.com/hiifyi/vps/blob/main/Jisshu/util/file_size.py"
    click HUMREAD "https://github.com/hiifyi/vps/blob/main/Jisshu/util/human_readable.py"
    click KEEPALIVE "https://github.com/hiifyi/vps/blob/main/Jisshu/util/keepalive.py"
    click RENDER "https://github.com/hiifyi/vps/blob/main/Jisshu/util/render_template.py"
    click TIMEFMT "https://github.com/hiifyi/vps/blob/main/Jisshu/util/time_format.py"
    click DLHTML "https://github.com/hiifyi/vps/blob/main/Jisshu/template/dl.html"
    click REQHTML "https://github.com/hiifyi/vps/blob/main/Jisshu/template/req.html"
    click CONFIGDB "https://github.com/hiifyi/vps/blob/main/database/config_db.py"
    click FILTERDB "https://github.com/hiifyi/vps/blob/main/database/ia_filterdb.py"
    click REFERDB "https://github.com/hiifyi/vps/blob/main/database/jsreferdb.py"
    click TOPDB "https://github.com/hiifyi/vps/blob/main/database/topdb.py"
    click USRCHATDB "https://github.com/hiifyi/vps/blob/main/database/users_chats_db.py"
    click BOTPY "https://github.com/hiifyi/vps/blob/main/bot.py"
    click MAINPY "https://github.com/hiifyi/vps/blob/main/main.py"
    click SCRIPTPY "https://github.com/hiifyi/vps/blob/main/Script.py"
    click APPPY "https://github.com/hiifyi/vps/blob/main/app.py"

    %% Styles
    classDef entry fill:#E0F7FA,stroke:#00796B,color:#004D40
    classDef config fill:#ECEFF1,stroke:#607D8B,color:#37474F
    classDef core fill:#BBDEFB,stroke:#1976D2,color:#0D47A1
    classDef plugin fill:#C8E6C9,stroke:#388E3C,color:#1B5E20
    classDef util fill:#F5F5F5,stroke:#9E9E9E,color:#424242
    classDef template fill:#FFF3E0,stroke:#FB8C00,color:#E65100
    classDef db fill:#FFE0B2,stroke:#F57C00,color:#E65100
    classDef external fill:#E1BEE7,stroke:#8E24AA,color:#4A148C
    classDef log fill:#F3E5F5,stroke:#CE93D8,color:#6A1B9A
```
