# vjbots/vj-file-store architecture

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

- Interactive diagram: https://gitdiagram.com/vjbots/vj-file-store
- Repository: https://github.com/vjbots/vj-file-store

## Overview

##### Project type and purpose
- This is a Python-based, full-stack Telegram file-storage bot with an integrated HTTP server for streaming and download links.
- Purpose: receive files via Telegram, store them (in a channel or on‐chain), generate permanent shareable and streamable URLs (with optional URL-shortener), support batch links, cloning of bot instances, auto-deletion, and custom start messages.

##### File structure
- Top-level scripts:
- bot.py – launches the Telegram bot
- app.py – launches the HTTP server (stream/download endpoints)
- config.py, logging.conf – central configuration
- Core Python package “TechVJ”:
- TechVJ/bot – orchestration of the Telegram client(s) (clients.py) and command handlers
- TechVJ/server – HTTP route definitions (stream_routes.py) and exception handling
- TechVJ/template – HTML templates for download/stream pages (dl.html, req.html)
- TechVJ/utils – cross-cutting utilities (config parsing, human-readable sizes, templating, keep-alive, time formatting)
- plugins/ and clone_plugins/ – modular commands and clone-bot feature extensions
- Dockerfile, Procfile, runtime.txt – containerization and deployment scripts
- requirements.txt – Python dependencies (Pyrogram or Telethon, FastAPI/Flask, Jinja2, Motor or PyMongo)

##### README for additional insights
- Confirms: Telegram API (API_ID/HASH/BOT_TOKEN), MongoDB (DB_URI, CLONE_DB_URI), web server URL, port.
- Features: permanent links via website, clone feature, streaming support, custom shortener, auto-delete, broadcast.

a. Main components
– Telegram Bot component (bot.py + TechVJ.bot + plugins)
– HTTP Server component (app.py + TechVJ.server + TechVJ.template)
– Utility library (TechVJ.utils)
– MongoDB database (user data, clone metadata, config)
– External services: Telegram API, URL-shortener API (optional)
– Clone-bot instances (spawned via clone_plugins)

b. Relationships & data flow
1. User ↔ Telegram Bot: commands (/link, /batch, /broadcast, etc.)
2. Bot ↔ MongoDB: store/retrieve user settings, tokens, custom URLs
3. Bot → HTTP Server: constructs stream/download URLs (pointing to the server)
4. User ↔ HTTP Server: HTTP GET /stream, /dl endpoints → streams or downloads file
5. HTTP Server ↔ TechVJ.utils: compute file metadata, render templates
6. Bot ↔ External URL-shortener API (if configured)

c. Architectural patterns & design principles
– Modular package organization: separate “bot” vs “server” vs “utils”
– Plugin architecture: commands and clone logic loaded dynamically from plugins/
– MVC-style for the server: stream_routes.py (controller), templates (view), utils (model/helper)
– Dependency injection via environment variables (config.py reads ENV)
– Loose coupling: both Bot and HTTP Server import from shared TechVJ library

d. Key technologies & frameworks
– Python 3.10
– Telegram client library (Pyrogram or Telethon)
– Web framework (FastAPI or Flask)
– Jinja2 for HTML templating
– MongoDB (Motor or PyMongo)
– Docker, Procfile for Heroku
– Logging via logging.conf

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User interaction
    User["User"]:::external

    %% Telegram Bot Process
    subgraph "Telegram Bot" 
        direction TB
        BotScript["bot.py"]:::botProc
        TBInit["TechVJ/bot/__init__.py"]:::botProc
        Clients["TechVJ/bot/clients.py"]:::botProc
        subgraph "plugins" 
            direction TB
            PCommands["commands.py"]:::plugin
            PGenlink["genlink.py"]:::plugin
            PBroadcast["broadcast.py"]:::plugin
            PDbusers["dbusers.py"]:::plugin
            PUsersAPI["users_api.py"]:::plugin
            PClone["clone.py"]:::plugin
        end
        subgraph "clone_plugins"
            direction TB
            CPCommands["commands.py"]:::plugin
            CPGenlink["genlink.py"]:::plugin
            CPBroadcast["broadcast.py"]:::plugin
            CPDbusers["dbusers.py"]:::plugin
            CPUsersAPI["users_api.py"]:::plugin
        end
    end

    %% HTTP Server Process
    subgraph "HTTP Server"
        direction TB
        AppScript["app.py"]:::serverProc
        SRoutes["TechVJ/server/stream_routes.py"]:::serverProc
        SExceptions["TechVJ/server/exceptions.py"]:::serverProc
        SInit["TechVJ/server/__init__.py"]:::serverProc
        subgraph "Templates"
            direction TB
            DHtml["dl.html"]:::template
            RHtml["req.html"]:::template
            TInit["TechVJ/template/__init__.py"]:::template
        end
    end

    %% Utilities
    subgraph "TechVJ/utils"
        direction TB
        ConfigParser["config_parser.py"]:::utils
        HumanReadable["human_readable.py"]:::utils
        FileSize["file_size.py"]:::utils
        FileProps["file_properties.py"]:::utils
        TimeFormat["time_format.py"]:::utils
        KeepAlive["keepalive.py"]:::utils
        RenderTemplate["render_template.py"]:::utils
        CustomDL["custom_dl.py"]:::utils
    end

    %% Configuration & Logging
    Config["config.py"]:::config
    Logging["logging.conf"]:::config

    %% Deployment
    Dockerfile["Dockerfile"]:::deploy
    Procfile["Procfile"]:::deploy
    Runtime["runtime.txt"]:::deploy
    Requirements["requirements.txt"]:::deploy

    %% Database
    MongoDB["MongoDB"]:::db

    %% External Services
    TelegramAPI["Telegram API"]:::external
    URLShortener["URL-Shortener API"]:::external

    %% Connections
    User -->|"Telegram commands (Pyrogram API)"| BotScript
    BotScript -->|"loads"| TBInit
    BotScript -->|"uses clients"| Clients
    BotScript -->|"loads plugins"| PCommands
    BotScript -->|"loads clone_plugins"| CPCommands
    BotScript -->|"reads ENV vars"| ConfigParser
    BotScript -->|"logs via"| Logging
    BotScript -->|"DB operations (Motor/PyMongo)"| MongoDB
    BotScript -->|"construct URL"| AppScript

    AppScript -->|"routes defined"| SRoutes
    AppScript -->|"handles exceptions"| SExceptions
    AppScript -->|"imports templates"| DHtml
    AppScript -->|"imports templates"| RHtml
    AppScript -->|"uses utils"| RenderTemplate
    AppScript -->|"keeps alive"| KeepAlive
    AppScript -->|"reads ENV vars"| ConfigParser
    AppScript -->|"logs via"| Logging

    User -->|"HTTP GET /stream,/dl"| AppScript
    AppScript -->|"stream/download via HTTP"| User

    SRoutes -->|"metadata & formatting"| FileProps
    SRoutes -->|"size formatting"| HumanReadable
    SRoutes -->|"time formatting"| TimeFormat

    BotScript -->|"calls send API"| TelegramAPI
    BotScript -->|"URL shorten request"| URLShortener

    BotScript -->|"shares clone metadata"| MongoDB
    CPCommands -->|"clone instance uses"| MongoDB

    ConfigParser -->|"provides config"| AppScript
    ConfigParser -->|"provides config"| BotScript

    %% Shared DB
    MongoDB -->|"shared data store"| SRoutes

    %% Click Events
    click BotScript "https://github.com/vjbots/vj-file-store/blob/main/bot.py"
    click Clients "https://github.com/vjbots/vj-file-store/blob/main/TechVJ/bot/clients.py"
    click TBInit "https://github.com/vjbots/vj-file-store/blob/main/TechVJ/bot/__init__.py"
    click AppScript "https://github.com/vjbots/vj-file-store/blob/main/app.py"
    click SRoutes "https://github.com/vjbots/vj-file-store/blob/main/TechVJ/server/stream_routes.py"
    click SExceptions "https://github.com/vjbots/vj-file-store/blob/main/TechVJ/server/exceptions.py"
    click SInit "https://github.com/vjbots/vj-file-store/blob/main/TechVJ/server/__init__.py"
    click DHtml "https://github.com/vjbots/vj-file-store/blob/main/TechVJ/template/dl.html"
    click RHtml "https://github.com/vjbots/vj-file-store/blob/main/TechVJ/template/req.html"
    click TInit "https://github.com/vjbots/vj-file-store/blob/main/TechVJ/template/__init__.py"
    click ConfigParser "https://github.com/vjbots/vj-file-store/blob/main/TechVJ/utils/config_parser.py"
    click HumanReadable "https://github.com/vjbots/vj-file-store/blob/main/TechVJ/utils/human_readable.py"
    click FileSize "https://github.com/vjbots/vj-file-store/blob/main/TechVJ/utils/file_size.py"
    click FileProps "https://github.com/vjbots/vj-file-store/blob/main/TechVJ/utils/file_properties.py"
    click TimeFormat "https://github.com/vjbots/vj-file-store/blob/main/TechVJ/utils/time_format.py"
    click KeepAlive "https://github.com/vjbots/vj-file-store/blob/main/TechVJ/utils/keepalive.py"
    click RenderTemplate "https://github.com/vjbots/vj-file-store/blob/main/TechVJ/utils/render_template.py"
    click CustomDL "https://github.com/vjbots/vj-file-store/blob/main/TechVJ/utils/custom_dl.py"
    click PCommands "https://github.com/vjbots/vj-file-store/blob/main/plugins/commands.py"
    click PGenlink "https://github.com/vjbots/vj-file-store/blob/main/plugins/genlink.py"
    click PBroadcast "https://github.com/vjbots/vj-file-store/blob/main/plugins/broadcast.py"
    click PDbusers "https://github.com/vjbots/vj-file-store/blob/main/plugins/dbusers.py"
    click PUsersAPI "https://github.com/vjbots/vj-file-store/blob/main/plugins/users_api.py"
    click PClone "https://github.com/vjbots/vj-file-store/blob/main/plugins/clone.py"
    click CPCommands "https://github.com/vjbots/vj-file-store/blob/main/clone_plugins/commands.py"
    click CPGenlink "https://github.com/vjbots/vj-file-store/blob/main/clone_plugins/genlink.py"
    click CPBroadcast "https://github.com/vjbots/vj-file-store/blob/main/clone_plugins/broadcast.py"
    click CPDbusers "https://github.com/vjbots/vj-file-store/blob/main/clone_plugins/dbusers.py"
    click CPUsersAPI "https://github.com/vjbots/vj-file-store/blob/main/clone_plugins/users_api.py"
    click Config "https://github.com/vjbots/vj-file-store/blob/main/config.py"
    click Logging "https://github.com/vjbots/vj-file-store/blob/main/logging.conf"
    click Dockerfile "https://github.com/vjbots/vj-file-store/tree/main/Dockerfile"
    click Procfile "https://github.com/vjbots/vj-file-store/tree/main/Procfile"
    click Runtime "https://github.com/vjbots/vj-file-store/blob/main/runtime.txt"
    click Requirements "https://github.com/vjbots/vj-file-store/blob/main/requirements.txt"

    %% Styles
    classDef botProc fill:#CCE5FF,stroke:#0000FF
    classDef serverProc fill:#CCE5FF,stroke:#0000FF
    classDef utils fill:#E8E8E8,stroke:#888888
    classDef db fill:#CCFFCC,stroke:#00AA00
    classDef external fill:#EEEEEE,stroke:#AAAAAA,stroke-dasharray: 5 5
    classDef plugin fill:#FFFFFF,stroke:#888888,stroke-dasharray: 2 2
    classDef template fill:#FFF0CC,stroke:#CC9900
    classDef config fill:#FFDCDC,stroke:#FF0000
    classDef deploy fill:#DDF0FF,stroke:#0077CC
```
