# sarveshhrathod/file-to-link architecture

> Architecture diagram of the GitHub repository sarveshhrathod/file-to-link, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sarveshhrathod/file-to-link
- Repository: https://github.com/sarveshhrathod/file-to-link

## Overview

1. This repository is a single Python service that combines a Telegram bot with a small HTTP server. The bot is the primary entrypoint for users, while the web server hosts the generated download and streaming pages/URLs.

2. The Telegram-facing side lives under `Adarsh/bot/`. `clients.py` likely creates the Pyrogram/Telegram client(s), and `plugins/` contains the handler groups: `start_help.py` for onboarding and help, `stream.py` for file-link generation and streaming actions, `admin.py` for owner/admin commands, and `extra.py` for miscellaneous commands and callbacks.

3. The main user flow is: a user sends or forwards a Telegram media file to the bot, the bot captures the file metadata and Telegram file reference, and then produces a “Get Download Link”/stream link instead of waiting for a full re-upload. The bot can also operate on channel posts, so the channel acts as an ingestion/source boundary as well as a publishing surface.

4. The `BIN_CHANNEL` is an important architectural boundary. Files are expected to be present in a Telegram channel the bot can access as admin; from there the bot can create links and update channel messages with buttons or link text. This keeps the actual file hosting external to the app and lets Telegram serve as the storage backend.

5. The HTTP layer is under `Adarsh/server/`. `stream_routes.py` exposes the web endpoints that likely back the direct download and streaming links, while `exceptions.py` holds server-side error handling. The HTML templates in `Adarsh/template/` define the user-facing pages for requesting a link and downloading/streaming a file.

6. Utilities in `Adarsh/utils/` provide most of the non-bot business logic. `custom_dl.py` appears to encapsulate the file-link/download behavior, `file_properties.py`, `file_size.py`, `human_readable.py`, and `time_format.py` format file and status metadata, `render_template.py` connects Python data to the HTML templates, and `config_parser.py`/`database.py` handle configuration and persistence concerns.

7. Persistence is narrow but important: MongoDB is used to store user IDs and support broadcasting. That means the bot has a lightweight state store for membership/recipients, separate from Telegram’s own file storage and separate from the web server’s stateless request handling.

8. Access control and operational checks are built into the bot flow. The README mentions password protection (`MY_PASS`), an optional updates channel gate, banned channels, and a “login” command, so requests can be filtered before a link is issued. This makes authorization a first-class part of the request pipeline.

9. Runtime and deployment are tuned for a hosted bot/web hybrid. `__main__.py` starts the application, `keepalive.py` suggests a ping/heartbeat mechanism for uptime hosts, and `Procfile`, `app.json`, and `runtime.txt` indicate Heroku-friendly deployment. The app is configured via environment variables in `vars.py` and the README’s `config.env` example.

10. From an architecture-diagram perspective, the key external systems are Telegram, MongoDB, and the hosting platform. The app itself sits in the middle, transforming Telegram media messages into HTTP-accessible stream/download links, storing only minimal user state, and serving lightweight HTML pages for the link experience.

Main entry points: [`Adarsh/server/stream_routes.py`](https://github.com/sarveshhrathod/file-to-link/blob/main/Adarsh/server/stream_routes.py) (Routes), [`Adarsh/__main__.py`](https://github.com/sarveshhrathod/file-to-link/blob/main/Adarsh/__main__.py) (Entry), [`Adarsh/bot/clients.py`](https://github.com/sarveshhrathod/file-to-link/blob/main/Adarsh/bot/clients.py) (Clients), [`Adarsh/bot/plugins/stream.py`](https://github.com/sarveshhrathod/file-to-link/blob/main/Adarsh/bot/plugins/stream.py) (Stream flow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_app["App core"]
  node_n_main["Entry<br/>startup<br/>[__main__.py]"]
  node_n_vars["Config<br/>[vars.py]"]
  node_n_keepalive(("Keepalive<br/>heartbeat<br/>[keepalive.py]"))
end

subgraph group_g_bot["Telegram bot"]
  node_n_clients["Clients<br/>[clients.py]"]
  node_n_start_help["Start/help<br/>onboarding handlers<br/>[start_help.py]"]
  node_n_stream["Stream flow<br/>link generation<br/>[stream.py]"]
  node_n_admin["Admin<br/>owner commands<br/>[admin.py]"]
  node_n_extra["Extra<br/>misc handlers<br/>[extra.py]"]
end

subgraph group_g_server["HTTP server"]
  node_n_routes["Routes<br/>http endpoints<br/>[stream_routes.py]"]
  node_n_exceptions["Errors<br/>[exceptions.py]"]
  node_n_req_tpl["Request page<br/>html template<br/>[req.html]"]
  node_n_dl_tpl["Download page<br/>html template<br/>[dl.html]"]
end

subgraph group_g_utils["Shared utils"]
  node_n_custom_dl["Link engine<br/>download logic<br/>[custom_dl.py]"]
  node_n_props["File props<br/>metadata<br/>[file_properties.py]"]
  node_n_formatting["Formatting<br/>format helpers<br/>[file_size.py]"]
  node_n_render["Render<br/>template bridge<br/>[render_template.py]"]
  node_n_db[("Database<br/>mongo persistence<br/>[database.py]")]
  node_n_broadcast(("Broadcast<br/>fanout helper"))
end

node_n_main -->|"boot"| node_n_clients
node_n_main -->|"serve"| node_n_routes
node_n_main -->|"load config"| node_n_vars
node_n_main -->|"ping"| node_n_keepalive
node_n_clients -->|"register"| node_n_start_help
node_n_clients -->|"register"| node_n_stream
node_n_clients -->|"register"| node_n_admin
node_n_clients -->|"register"| node_n_extra
node_n_stream -->|"generate"| node_n_custom_dl
node_n_stream -->|"inspect"| node_n_props
node_n_stream -->|"format"| node_n_formatting
node_n_stream -->|"store"| node_n_db
node_n_admin -->|"fanout"| node_n_broadcast
node_n_broadcast -->|"read recipients"| node_n_db
node_n_routes -->|"render pages"| node_n_render
node_n_routes -->|"uses"| node_n_req_tpl
node_n_routes -->|"uses"| node_n_dl_tpl
node_n_routes -->|"resolve links"| node_n_custom_dl
node_n_routes -->|"handle errors"| node_n_exceptions
node_n_render -->|"fill"| node_n_req_tpl
node_n_render -->|"fill"| node_n_dl_tpl
node_n_custom_dl -->|"uses"| node_n_props
node_n_custom_dl -->|"uses"| node_n_formatting
node_n_keepalive -->|"config"| node_n_vars
node_n_main -->|"init state"| node_n_db

click node_n_main "https://github.com/sarveshhrathod/file-to-link/blob/main/Adarsh/__main__.py"
click node_n_vars "https://github.com/sarveshhrathod/file-to-link/blob/main/Adarsh/vars.py"
click node_n_keepalive "https://github.com/sarveshhrathod/file-to-link/blob/main/Adarsh/utils/keepalive.py"
click node_n_clients "https://github.com/sarveshhrathod/file-to-link/blob/main/Adarsh/bot/clients.py"
click node_n_start_help "https://github.com/sarveshhrathod/file-to-link/blob/main/Adarsh/bot/plugins/start_help.py"
click node_n_stream "https://github.com/sarveshhrathod/file-to-link/blob/main/Adarsh/bot/plugins/stream.py"
click node_n_admin "https://github.com/sarveshhrathod/file-to-link/blob/main/Adarsh/bot/plugins/admin.py"
click node_n_extra "https://github.com/sarveshhrathod/file-to-link/blob/main/Adarsh/bot/plugins/extra.py"
click node_n_routes "https://github.com/sarveshhrathod/file-to-link/blob/main/Adarsh/server/stream_routes.py"
click node_n_exceptions "https://github.com/sarveshhrathod/file-to-link/blob/main/Adarsh/server/exceptions.py"
click node_n_req_tpl "https://github.com/sarveshhrathod/file-to-link/blob/main/Adarsh/template/req.html"
click node_n_dl_tpl "https://github.com/sarveshhrathod/file-to-link/blob/main/Adarsh/template/dl.html"
click node_n_custom_dl "https://github.com/sarveshhrathod/file-to-link/blob/main/Adarsh/utils/custom_dl.py"
click node_n_props "https://github.com/sarveshhrathod/file-to-link/blob/main/Adarsh/utils/file_properties.py"
click node_n_formatting "https://github.com/sarveshhrathod/file-to-link/blob/main/Adarsh/utils/file_size.py"
click node_n_render "https://github.com/sarveshhrathod/file-to-link/blob/main/Adarsh/utils/render_template.py"
click node_n_db "https://github.com/sarveshhrathod/file-to-link/blob/main/Adarsh/utils/database.py"
click node_n_broadcast "https://github.com/sarveshhrathod/file-to-link/blob/main/Adarsh/utils/broadcast_helper.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n_main,node_n_vars,node_n_keepalive toneBlue
class node_n_clients,node_n_start_help,node_n_stream,node_n_admin,node_n_extra toneAmber
class node_n_routes,node_n_exceptions,node_n_req_tpl,node_n_dl_tpl toneMint
class node_n_custom_dl,node_n_props,node_n_formatting,node_n_render,node_n_db,node_n_broadcast toneRose
```

## Components

### App core

Main Python service that coordinates bot, web server, and startup.

- [Entry](https://github.com/sarveshhrathod/file-to-link/blob/main/Adarsh/__main__.py): startup · Starts the application and wires bot plus server. · `Adarsh/__main__.py`
- [Config](https://github.com/sarveshhrathod/file-to-link/blob/main/Adarsh/vars.py): env config · Environment-driven runtime settings and secrets. · `Adarsh/vars.py`
- [Keepalive](https://github.com/sarveshhrathod/file-to-link/blob/main/Adarsh/utils/keepalive.py): heartbeat · Hosting uptime ping/health support. · `Adarsh/utils/keepalive.py`

### Telegram bot

Telegram-facing entrypoints, handlers, and file-link flow.

- [Clients](https://github.com/sarveshhrathod/file-to-link/blob/main/Adarsh/bot/clients.py): telegram clients · Creates and configures Telegram/Pyrogram clients. · `Adarsh/bot/clients.py`
- [Start/help](https://github.com/sarveshhrathod/file-to-link/blob/main/Adarsh/bot/plugins/start_help.py): onboarding handlers · Greeting, help, and basic user entry flow. · `Adarsh/bot/plugins/start_help.py`
- [Stream flow](https://github.com/sarveshhrathod/file-to-link/blob/main/Adarsh/bot/plugins/stream.py): link generation · Handles media intake and produces download/stream links. · `Adarsh/bot/plugins/stream.py`
- [Admin](https://github.com/sarveshhrathod/file-to-link/blob/main/Adarsh/bot/plugins/admin.py): owner commands · Owner/admin controls and operational commands. · `Adarsh/bot/plugins/admin.py`
- [Extra](https://github.com/sarveshhrathod/file-to-link/blob/main/Adarsh/bot/plugins/extra.py): misc handlers · Additional commands, callbacks, and support actions. · `Adarsh/bot/plugins/extra.py`

### HTTP server

Web endpoints and templates used for download/stream pages.

- [Routes](https://github.com/sarveshhrathod/file-to-link/blob/main/Adarsh/server/stream_routes.py): http endpoints · Web endpoints that serve link pages and file access paths. · `Adarsh/server/stream_routes.py`
- [Errors](https://github.com/sarveshhrathod/file-to-link/blob/main/Adarsh/server/exceptions.py): server errors · HTTP/server-side exception handling. · `Adarsh/server/exceptions.py`
- [Request page](https://github.com/sarveshhrathod/file-to-link/blob/main/Adarsh/template/req.html): html template · Page for requesting or initiating a file link. · `Adarsh/template/req.html`
- [Download page](https://github.com/sarveshhrathod/file-to-link/blob/main/Adarsh/template/dl.html): html template · Page for downloading or streaming a file. · `Adarsh/template/dl.html`

### Shared utils

Business logic, formatting, persistence, and support helpers.

- [Link engine](https://github.com/sarveshhrathod/file-to-link/blob/main/Adarsh/utils/custom_dl.py): download logic · Encapsulates file-link and download behavior. · `Adarsh/utils/custom_dl.py`
- [File props](https://github.com/sarveshhrathod/file-to-link/blob/main/Adarsh/utils/file_properties.py): metadata · Extracts file properties and identifiers. · `Adarsh/utils/file_properties.py`
- [Formatting](https://github.com/sarveshhrathod/file-to-link/blob/main/Adarsh/utils/file_size.py): format helpers · File size, human-readable, and time formatting helpers. · `Adarsh/utils/file_size.py`
- [Render](https://github.com/sarveshhrathod/file-to-link/blob/main/Adarsh/utils/render_template.py): template bridge · Renders Python data into HTML templates. · `Adarsh/utils/render_template.py`
- [Database](https://github.com/sarveshhrathod/file-to-link/blob/main/Adarsh/utils/database.py): mongo persistence · Stores user IDs and broadcast-related state. · `Adarsh/utils/database.py`
- [Broadcast](https://github.com/sarveshhrathod/file-to-link/blob/main/Adarsh/utils/broadcast_helper.py): fanout helper · Supports broadcast messaging to stored recipients. · `Adarsh/utils/broadcast_helper.py`

## Connections

- Entry → Clients: boot · Initializes Telegram clients and handlers.
- Entry → Routes: serve · Starts the HTTP layer for download/stream pages.
- Entry → Config: load config · Reads runtime configuration from environment and parser state.
- Entry → Keepalive: ping · Enables uptime/heartbeat behavior for hosted deployments.
- Clients → Start/help: register · Attaches onboarding handlers.
- Clients → Stream flow: register · Attaches media-to-link handlers.
- Clients → Admin: register · Attaches owner/admin commands.
- Clients → Extra: register · Attaches miscellaneous commands and callbacks.
- Stream flow → Link engine: generate · Uses link/download logic to create streamable URLs.
- Stream flow → File props: inspect · Reads media metadata and file reference details.
- Stream flow → Formatting: format · Formats size and status text for users.
- Stream flow → Database: store · Persists user or request state when needed.
- Admin → Broadcast: fanout · Uses broadcast support for owner messaging.
- Broadcast → Database: read recipients · Pulls recipient identifiers from persistence.
- Routes → Render: render pages · Builds HTML responses from template data.
- Routes → Request page: uses · Serves the request page template.
- Routes → Download page: uses · Serves the download/stream page template.
- Routes → Link engine: resolve links · Connects HTTP requests to file-link behavior.
- Routes → Errors: handle errors · Routes server failures through centralized handling.
- Render → Request page: fill · Renders request page context.
- Render → Download page: fill · Renders download page context.
- Link engine → File props: uses · Depends on file metadata to build responses.
- Link engine → Formatting: uses · Formats sizes, durations, and human-readable text.
- Keepalive → Config: config · Uses deployment settings for ping behavior.
- Entry → Database: init state · Ensures persistence is available at startup.