# everythingsuckz/tg-filestreambot architecture

> Architecture diagram of the GitHub repository everythingsuckz/tg-filestreambot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/everythingsuckz/tg-filestreambot
- Repository: https://github.com/everythingsuckz/tg-filestreambot

## Overview

#### Purpose and Runtime

TG-FileStreamBot is a Go service that turns Telegram-hosted files into direct HTTP streaming/download links. It combines a Telegram bot interface with an HTTP server and a Telegram user-session client used to retrieve file bytes.

Primary executable: `cmd/fsb/main.go`. Process startup, bot/session initialization, and service orchestration are organized in `cmd/fsb/run.go` and `cmd/fsb/session.go`.

#### Bootstrap and Configuration

`cmd/fsb/main.go` launches the application; `cmd/fsb/run.go` composes the major subsystems. `config/config.go` is the central configuration boundary, likely sourcing bot credentials, Telegram API/session settings, server configuration, and cache behavior from environment variables.

Deployment targets include containerized and process-platform environments via `Dockerfile`, `docker-compose.yaml`, and `Procfile`.

#### Telegram Interaction Layer

The Telegram-facing application is implemented in `internal/bot/userbot.go`, `internal/bot/client.go`, and `internal/bot/middleware.go`. This layer owns Telegram client connectivity, incoming update handling, and cross-cutting bot validation/error behavior.

Command dispatch lives in `internal/commands/commands.go`. User-facing workflows include startup/onboarding in `internal/commands/start.go` and generation of stream links from Telegram messages/files in `internal/commands/stream.go`.

#### File-Link and Response Flow

A user submits or references a Telegram file through the bot. The command layer resolves file metadata and produces a stream-link response using shared models in `internal/types/file.go` and `internal/types/response.go`.

Link generation and file-access identity depend on utility functions such as hashing in `internal/utils/hashing.go`. This separates externally exposed stream identifiers from Telegram’s underlying file references.

#### HTTP Routing and Stream Delivery

The public HTTP boundary is defined by `internal/routes/routes.go`, with stream-specific endpoint handling in `internal/routes/stream.go`. These handlers accept a generated link/request, resolve the corresponding Telegram file, and return an HTTP response suitable for browser/media-client consumption.

Actual transfer is handled by `internal/stream/pipe.go`; stream failures are modeled in `internal/stream/errors.go`. This is the key protocol boundary: HTTP request/response semantics on one side, Telegram file retrieval on the other.

#### Session, Caching, and Background Work

Telegram user authorization/session lifecycle is coordinated from `cmd/fsb/session.go`; QR-login support is packaged in `pkg/qrlogin/qrcode.go` and `pkg/qrlogin/encoder.go`. This supports authenticated Telegram file access independently of the bot command channel.

`internal/cache/cache.go` provides a state/cache boundary for reusable file or link-related data. `internal/bot/workers.go` contains asynchronous/background bot work, keeping long-running or deferred tasks outside the immediate update handler path.

#### External Dependencies and Operational Boundaries

The system integrates with Telegram through bot and user-client APIs, including the credited `gotgproto` ecosystem. Telegram is the authoritative file source; the service exposes the derived HTTP streaming surface. Runtime observability/logging utilities are centralized in `internal/utils/logger.go`, while releases are built and packaged through `.goreleaser.yaml` and GitHub release automation.

Main entry points: [`cmd/fsb/run.go`](https://github.com/everythingsuckz/tg-filestreambot/blob/main/cmd/fsb/run.go) (Service orchestration), [`internal/bot/userbot.go`](https://github.com/everythingsuckz/tg-filestreambot/blob/main/internal/bot/userbot.go) (Bot client and updates), [`internal/commands/stream.go`](https://github.com/everythingsuckz/tg-filestreambot/blob/main/internal/commands/stream.go) (Stream-link workflow), [`cmd/fsb/session.go`](https://github.com/everythingsuckz/tg-filestreambot/blob/main/cmd/fsb/session.go) (User session lifecycle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_main["Application entrypoint<br/>Go executable<br/>[main.go]"]
  node_run["Service orchestration<br/>bootstrap<br/>[run.go]"]
  node_config["Configuration<br/>config boundary<br/>[config.go]"]
  node_session["User session lifecycle<br/>Telegram authorization<br/>[session.go]"]
  node_qrlogin["QR login<br/>authentication support<br/>[qrcode.go]"]
end

subgraph group_telegram["Telegram interaction"]
  node_bot["Bot client and updates<br/>Telegram bot layer<br/>[userbot.go]"]
  node_commands["Command dispatch<br/>command layer<br/>[commands.go]"]
  node_stream_command["Stream-link workflow<br/>command handler<br/>[stream.go]"]
  node_workers["Background workers<br/>async work<br/>[workers.go]"]
end

subgraph group_delivery["HTTP delivery"]
  node_routes["HTTP routing<br/>public HTTP boundary<br/>[routes.go]"]
  node_stream_route["Stream endpoint<br/>HTTP handler<br/>[stream.go]"]
  node_pipe["HTTP-to-Telegram pipe<br/>stream transfer<br/>[pipe.go]"]
end

subgraph group_support["State and support"]
  node_cache[("File/link cache<br/>state cache<br/>[cache.go]")]
  node_file_models["File and response models<br/>shared models<br/>[file.go]"]
  node_hashing["Stream identity hashing<br/>identifier utility<br/>[hashing.go]"]
  node_logger["Logging<br/>observability<br/>[logger.go]"]
end

node_telegram_api{{"Telegram APIs<br/>external platform"}}
node_http_clients(("Browsers and media clients<br/>external consumers"))

node_main -->|"starts"| node_run
node_run -->|"loads"| node_config
node_run -->|"initializes"| node_session
node_session -->|"uses when authorizing"| node_qrlogin
node_session -->|"authenticates user client"| node_telegram_api
node_run -->|"starts"| node_bot
node_bot -->|"receives updates"| node_telegram_api
node_bot -->|"dispatches"| node_commands
node_bot -->|"queues deferred work"| node_workers
node_commands -->|"routes stream requests"| node_stream_command
node_stream_command -->|"uses"| node_file_models
node_stream_command -->|"creates link identity"| node_hashing
node_stream_command -->|"stores lookup state"| node_cache
node_run -->|"serves"| node_routes
node_http_clients -->|"HTTP requests"| node_routes
node_routes -->|"matches stream endpoint"| node_stream_route
node_stream_route -->|"resolves link state"| node_cache
node_stream_route -->|"streams file"| node_pipe
node_pipe -->|"retrieves file bytes"| node_telegram_api
node_pipe -->|"HTTP response"| node_http_clients
node_run -->|"configures"| node_logger

click node_main "https://github.com/everythingsuckz/tg-filestreambot/blob/main/cmd/fsb/main.go"
click node_run "https://github.com/everythingsuckz/tg-filestreambot/blob/main/cmd/fsb/run.go"
click node_config "https://github.com/everythingsuckz/tg-filestreambot/blob/main/config/config.go"
click node_session "https://github.com/everythingsuckz/tg-filestreambot/blob/main/cmd/fsb/session.go"
click node_qrlogin "https://github.com/everythingsuckz/tg-filestreambot/blob/main/pkg/qrlogin/qrcode.go"
click node_bot "https://github.com/everythingsuckz/tg-filestreambot/blob/main/internal/bot/userbot.go"
click node_commands "https://github.com/everythingsuckz/tg-filestreambot/blob/main/internal/commands/commands.go"
click node_stream_command "https://github.com/everythingsuckz/tg-filestreambot/blob/main/internal/commands/stream.go"
click node_workers "https://github.com/everythingsuckz/tg-filestreambot/blob/main/internal/bot/workers.go"
click node_routes "https://github.com/everythingsuckz/tg-filestreambot/blob/main/internal/routes/routes.go"
click node_stream_route "https://github.com/everythingsuckz/tg-filestreambot/blob/main/internal/routes/stream.go"
click node_pipe "https://github.com/everythingsuckz/tg-filestreambot/blob/main/internal/stream/pipe.go"
click node_cache "https://github.com/everythingsuckz/tg-filestreambot/blob/main/internal/cache/cache.go"
click node_file_models "https://github.com/everythingsuckz/tg-filestreambot/blob/main/internal/types/file.go"
click node_hashing "https://github.com/everythingsuckz/tg-filestreambot/blob/main/internal/utils/hashing.go"
click node_logger "https://github.com/everythingsuckz/tg-filestreambot/blob/main/internal/utils/logger.go"

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_main,node_run,node_config,node_session,node_qrlogin toneBlue
class node_bot,node_commands,node_stream_command,node_workers toneAmber
class node_routes,node_stream_route,node_pipe toneMint
class node_cache,node_file_models,node_hashing,node_logger toneRose
class node_telegram_api,node_http_clients toneNeutral
```

## Components

### Runtime

- [Application entrypoint](https://github.com/everythingsuckz/tg-filestreambot/blob/main/cmd/fsb/main.go): Go executable · `cmd/fsb/main.go`
- [Service orchestration](https://github.com/everythingsuckz/tg-filestreambot/blob/main/cmd/fsb/run.go): bootstrap · Composes bot, session, and HTTP services. · `cmd/fsb/run.go`
- [Configuration](https://github.com/everythingsuckz/tg-filestreambot/blob/main/config/config.go): config boundary · Supplies credentials, server, session, and cache settings. · `config/config.go`
- [User session lifecycle](https://github.com/everythingsuckz/tg-filestreambot/blob/main/cmd/fsb/session.go): Telegram authorization · `cmd/fsb/session.go`
- [QR login](https://github.com/everythingsuckz/tg-filestreambot/blob/main/pkg/qrlogin/qrcode.go): authentication support · `pkg/qrlogin/qrcode.go`

### Telegram interaction

- [Bot client and updates](https://github.com/everythingsuckz/tg-filestreambot/blob/main/internal/bot/userbot.go): Telegram bot layer · Owns connectivity, update handling, and middleware. · `internal/bot/userbot.go`
- [Command dispatch](https://github.com/everythingsuckz/tg-filestreambot/blob/main/internal/commands/commands.go): command layer · `internal/commands/commands.go`
- [Stream-link workflow](https://github.com/everythingsuckz/tg-filestreambot/blob/main/internal/commands/stream.go): command handler · Resolves Telegram files and returns stream links. · `internal/commands/stream.go`
- [Background workers](https://github.com/everythingsuckz/tg-filestreambot/blob/main/internal/bot/workers.go): async work · `internal/bot/workers.go`

### HTTP delivery

- [HTTP routing](https://github.com/everythingsuckz/tg-filestreambot/blob/main/internal/routes/routes.go): public HTTP boundary · `internal/routes/routes.go`
- [Stream endpoint](https://github.com/everythingsuckz/tg-filestreambot/blob/main/internal/routes/stream.go): HTTP handler · Resolves generated stream requests. · `internal/routes/stream.go`
- [HTTP-to-Telegram pipe](https://github.com/everythingsuckz/tg-filestreambot/blob/main/internal/stream/pipe.go): stream transfer · Bridges HTTP response semantics to Telegram file retrieval. · `internal/stream/pipe.go`

### State and support

- [File/link cache](https://github.com/everythingsuckz/tg-filestreambot/blob/main/internal/cache/cache.go): state cache · `internal/cache/cache.go`
- [File and response models](https://github.com/everythingsuckz/tg-filestreambot/blob/main/internal/types/file.go): shared models · `internal/types/file.go`
- [Stream identity hashing](https://github.com/everythingsuckz/tg-filestreambot/blob/main/internal/utils/hashing.go): identifier utility · Separates public identifiers from Telegram file references. · `internal/utils/hashing.go`
- [Logging](https://github.com/everythingsuckz/tg-filestreambot/blob/main/internal/utils/logger.go): observability · `internal/utils/logger.go`

### Other components

- **Telegram APIs**: external platform · Bot updates and authoritative file source.
- **Browsers and media clients**: external consumers

## Connections

- Application entrypoint → Service orchestration: starts
- Service orchestration → Configuration: loads
- Service orchestration → User session lifecycle: initializes
- User session lifecycle → QR login: uses when authorizing
- User session lifecycle → Telegram APIs: authenticates user client
- Service orchestration → Bot client and updates: starts
- Bot client and updates → Telegram APIs: receives updates
- Bot client and updates → Command dispatch: dispatches
- Bot client and updates → Background workers: queues deferred work
- Command dispatch → Stream-link workflow: routes stream requests
- Stream-link workflow → File and response models: uses
- Stream-link workflow → Stream identity hashing: creates link identity
- Stream-link workflow → File/link cache: stores lookup state
- Service orchestration → HTTP routing: serves
- Browsers and media clients → HTTP routing: HTTP requests
- HTTP routing → Stream endpoint: matches stream endpoint
- Stream endpoint → File/link cache: resolves link state
- Stream endpoint → HTTP-to-Telegram pipe: streams file
- HTTP-to-Telegram pipe → Telegram APIs: retrieves file bytes
- HTTP-to-Telegram pipe → Browsers and media clients: HTTP response
- Service orchestration → Logging: configures