# al3xfight/telegram-uploader architecture

> Architecture diagram of the GitHub repository al3xfight/telegram-uploader, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/al3xfight/telegram-uploader
- Repository: https://github.com/al3xfight/telegram-uploader

## Overview

Telegram Uploader is a bilingual command-line application that uploads files to a private Telegram channel or group using the user's own account through Telethon. The workflow configures credentials, scans and chronologically orders a folder, filters files already recorded as uploaded, then uploads pending files with optional parallel chunks, media metadata, retries, and pacing. Successful uploads update a local JSON registry. The graph reflects documented capabilities where their implementation was not sampled; optional ffmpeg support is marked separately.

Main entry points: [`telegram_uploader/cli.py`](https://github.com/al3xfight/telegram-uploader/blob/main/telegram_uploader/cli.py) (Command workflow), [`telegram_uploader/subida.py`](https://github.com/al3xfight/telegram-uploader/blob/main/telegram_uploader/subida.py) (Upload orchestration), [`telegram_uploader/registro.py`](https://github.com/al3xfight/telegram-uploader/blob/main/telegram_uploader/registro.py) (Upload registry), [`telegram_uploader/config.py`](https://github.com/al3xfight/telegram-uploader/blob/main/telegram_uploader/config.py) (Configuration wizard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and configuration"]
  node_launcher["CLI launcher"]
  node_cli["Command workflow<br/>[cli.py]"]
  node_settings["Configuration wizard<br/>[config.py]"]
  node_configfile[("config.json")]
end

subgraph group_selection["File selection"]
  node_folder[("Local files")]
  node_discovery["File discovery<br/>[medios.py]"]
  node_ordering["Chronological ordering<br/>[medios.py]"]
  node_dedup["Pending-file filter<br/>[cli.py]"]
  node_registry["Upload registry<br/>[registro.py]"]
  node_registryfile[("subidos.json")]
end

subgraph group_transfer["Upload and Telegram"]
  node_upload["Upload orchestration<br/>[subida.py]"]
  node_parallel["Parallel chunks<br/>[subida.py]"]
  node_media["Video metadata and thumbnails<br/>[medios.py]"]
end

subgraph group_support["Shared support"]
  node_language["Translations<br/>[i18n.py]"]
  node_console["Console and logging<br/>[consola.py]"]
  node_constants["Defaults and paths<br/>[constantes.py]"]
end

node_user(("User"))
node_telegram{{"Telegram service"}}
node_ffmpeg{{"ffprobe / ffmpeg"}}

node_user -->|"runs"| node_launcher
node_launcher -->|"invokes"| node_cli
node_cli -->|"loads settings"| node_settings
node_settings -->|"reads and writes"| node_configfile
node_cli -->|"loads settings"| node_configfile
node_cli -->|"finds files"| node_discovery
node_cli -->|"sorts by date"| node_ordering
node_cli -->|"checks uploads"| node_registry
node_discovery -->|"scans"| node_folder
node_ordering -->|"reads metadata"| node_folder
node_cli -->|"filters pending"| node_dedup
node_dedup -->|"checks keys"| node_registry
node_registry -->|"reads and writes"| node_registryfile
node_cli -->|"starts uploads"| node_upload
node_upload -->|"uploads chunks"| node_parallel
node_upload -->|"gets video details"| node_media
node_media -.->|"extracts media data"| node_ffmpeg
node_upload -->|"sends files"| node_telegram
node_cli -->|"starts session"| node_telegram
node_upload -->|"records success"| node_registry
node_cli -->|"selects language"| node_language
node_settings -->|"uses translations"| node_language
node_cli -->|"prints status"| node_console
node_settings -->|"prompts user"| node_console
node_upload -->|"logs progress"| node_console
node_cli -->|"uses defaults"| node_constants
node_upload -->|"uses upload limits"| node_constants
node_registry -->|"uses registry path"| node_constants

click node_launcher "https://github.com/al3xfight/telegram-uploader/blob/main/subir_a_telegram.py"
click node_cli "https://github.com/al3xfight/telegram-uploader/blob/main/telegram_uploader/cli.py"
click node_settings "https://github.com/al3xfight/telegram-uploader/blob/main/telegram_uploader/config.py"
click node_discovery "https://github.com/al3xfight/telegram-uploader/blob/main/telegram_uploader/medios.py"
click node_ordering "https://github.com/al3xfight/telegram-uploader/blob/main/telegram_uploader/medios.py"
click node_dedup "https://github.com/al3xfight/telegram-uploader/blob/main/telegram_uploader/cli.py"
click node_registry "https://github.com/al3xfight/telegram-uploader/blob/main/telegram_uploader/registro.py"
click node_upload "https://github.com/al3xfight/telegram-uploader/blob/main/telegram_uploader/subida.py"
click node_parallel "https://github.com/al3xfight/telegram-uploader/blob/main/telegram_uploader/subida.py"
click node_media "https://github.com/al3xfight/telegram-uploader/blob/main/telegram_uploader/medios.py"
click node_language "https://github.com/al3xfight/telegram-uploader/blob/main/telegram_uploader/i18n.py"
click node_console "https://github.com/al3xfight/telegram-uploader/blob/main/telegram_uploader/consola.py"
click node_constants "https://github.com/al3xfight/telegram-uploader/blob/main/telegram_uploader/constantes.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_launcher,node_cli,node_settings,node_configfile,node_user toneBlue
class node_folder,node_discovery,node_ordering,node_dedup,node_registry,node_registryfile toneAmber
class node_upload,node_parallel,node_media toneMint
class node_language,node_console,node_constants toneRose
class node_telegram,node_ffmpeg toneIndigo
```

## Components

### CLI and configuration

- [CLI launcher](https://github.com/al3xfight/telegram-uploader/blob/main/subir_a_telegram.py): `subir_a_telegram.py`
- [Command workflow](https://github.com/al3xfight/telegram-uploader/blob/main/telegram_uploader/cli.py): `telegram_uploader/cli.py`
- [Configuration wizard](https://github.com/al3xfight/telegram-uploader/blob/main/telegram_uploader/config.py): `telegram_uploader/config.py`
- **config.json**

### File selection

- **Local files**
- [File discovery](https://github.com/al3xfight/telegram-uploader/blob/main/telegram_uploader/medios.py): `telegram_uploader/medios.py`
- [Chronological ordering](https://github.com/al3xfight/telegram-uploader/blob/main/telegram_uploader/medios.py): `telegram_uploader/medios.py`
- [Pending-file filter](https://github.com/al3xfight/telegram-uploader/blob/main/telegram_uploader/cli.py): `telegram_uploader/cli.py`
- [Upload registry](https://github.com/al3xfight/telegram-uploader/blob/main/telegram_uploader/registro.py): `telegram_uploader/registro.py`
- **subidos.json**

### Upload and Telegram

- [Upload orchestration](https://github.com/al3xfight/telegram-uploader/blob/main/telegram_uploader/subida.py): `telegram_uploader/subida.py`
- [Parallel chunks](https://github.com/al3xfight/telegram-uploader/blob/main/telegram_uploader/subida.py): `telegram_uploader/subida.py`
- [Video metadata and thumbnails](https://github.com/al3xfight/telegram-uploader/blob/main/telegram_uploader/medios.py): `telegram_uploader/medios.py`

### Shared support

- [Translations](https://github.com/al3xfight/telegram-uploader/blob/main/telegram_uploader/i18n.py): `telegram_uploader/i18n.py`
- [Console and logging](https://github.com/al3xfight/telegram-uploader/blob/main/telegram_uploader/consola.py): `telegram_uploader/consola.py`
- [Defaults and paths](https://github.com/al3xfight/telegram-uploader/blob/main/telegram_uploader/constantes.py): `telegram_uploader/constantes.py`

### Other components

- **User**
- **Telegram service**
- **ffprobe / ffmpeg**

## Connections

- User → CLI launcher: runs (evidence: `README.md`)
- CLI launcher → Command workflow: invokes (evidence: `subir_a_telegram.py`)
- Command workflow → Configuration wizard: loads settings (evidence: `telegram_uploader/cli.py`)
- Configuration wizard → config.json: reads and writes (evidence: `telegram_uploader/config.py`)
- Command workflow → config.json: loads settings (evidence: `telegram_uploader/cli.py`)
- Command workflow → File discovery: finds files (evidence: `telegram_uploader/cli.py`)
- Command workflow → Chronological ordering: sorts by date (evidence: `telegram_uploader/cli.py`)
- Command workflow → Upload registry: checks uploads (evidence: `telegram_uploader/cli.py`)
- File discovery → Local files: scans (evidence: `telegram_uploader/medios.py`)
- Chronological ordering → Local files: reads metadata (evidence: `telegram_uploader/medios.py`)
- Command workflow → Pending-file filter: filters pending (evidence: `telegram_uploader/cli.py`)
- Pending-file filter → Upload registry: checks keys (evidence: `telegram_uploader/cli.py`)
- Upload registry → subidos.json: reads and writes (evidence: `telegram_uploader/registro.py`)
- Command workflow → Upload orchestration: starts uploads (evidence: `telegram_uploader/cli.py`)
- Upload orchestration → Parallel chunks: uploads chunks (evidence: `telegram_uploader/subida.py`)
- Upload orchestration → Video metadata and thumbnails: gets video details (evidence: `telegram_uploader/subida.py`)
- Video metadata and thumbnails → ffprobe / ffmpeg: extracts media data (evidence: `telegram_uploader/medios.py`)
- Upload orchestration → Telegram service: sends files (evidence: `telegram_uploader/subida.py`)
- Command workflow → Telegram service: starts session (evidence: `telegram_uploader/cli.py`)
- Upload orchestration → Upload registry: records success (evidence: `telegram_uploader/subida.py`)
- Command workflow → Translations: selects language (evidence: `telegram_uploader/cli.py`)
- Configuration wizard → Translations: uses translations (evidence: `telegram_uploader/config.py`)
- Command workflow → Console and logging: prints status (evidence: `telegram_uploader/cli.py`)
- Configuration wizard → Console and logging: prompts user (evidence: `telegram_uploader/config.py`)
- Upload orchestration → Console and logging: logs progress (evidence: `telegram_uploader/subida.py`)
- Command workflow → Defaults and paths: uses defaults (evidence: `telegram_uploader/cli.py`)
- Upload orchestration → Defaults and paths: uses upload limits (evidence: `telegram_uploader/subida.py`)
- Upload registry → Defaults and paths: uses registry path (evidence: `telegram_uploader/registro.py`)