# vengatz-git/file-downloader architecture

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

- Interactive diagram: https://gitdiagram.com/vengatz-git/file-downloader
- Repository: https://github.com/vengatz-git/file-downloader

## Overview

Telegram File Downloader resolves Telegram message links through a VPS-hosted MTProto backend, then streams media to either the web/PWA client or the Android app. The Python and Node.js backends are alternative implementations. The graph follows the documented resolve-to-stream flow and sampled Android/Python calls; web, Node.js, and some UI wiring are represented only where the README documents them.

Main entry points: [`backend/app/main.py`](https://github.com/vengatz-git/file-downloader/blob/main/backend/app/main.py) (FastAPI app), [`web/app.js`](https://github.com/vengatz-git/file-downloader/blob/main/web/app.js) (Web downloader), [`android/app/src/main/java/com/tgdownloader/app/ui/screen/MainScreen.kt`](https://github.com/vengatz-git/file-downloader/blob/main/android/app/src/main/java/com/tgdownloader/app/ui/screen/MainScreen.kt) (Downloader screen), [`android/app/src/main/java/com/tgdownloader/app/ui/viewmodel/MainViewModel.kt`](https://github.com/vengatz-git/file-downloader/blob/main/android/app/src/main/java/com/tgdownloader/app/ui/viewmodel/MainViewModel.kt) (Download state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web client"]
  node_webapp["Web downloader<br/>[app.js]"]
  node_webpwa["PWA shell<br/>[sw.js]"]
end

subgraph group_android["Android client"]
  node_activity["App entry<br/>[MainActivity.kt]"]
  node_screen["Downloader screen<br/>[MainScreen.kt]"]
  node_viewmodel["Download state<br/>[MainViewModel.kt]"]
  node_uistate["UI state<br/>[MainUiState.kt]"]
  node_domain["File and progress models<br/>[FileMetadata.kt]"]
  node_repository["Download repository"]
  node_contract["Repository contract"]
  node_api["HTTP API client"]
  node_network["Network setup<br/>[NetworkModule.kt]"]
  node_androidtheme["Compose theme<br/>[Color.kt]"]
end

subgraph group_python["Python backend"]
  node_pythonapp["FastAPI app<br/>[main.py]"]
  node_routes["Resolve and stream routes<br/>[routes.py]"]
  node_telegram["Telethon manager<br/>[telegram.py]"]
  node_config["Backend settings<br/>[config.py]"]
  node_schemas["API schemas<br/>[file.py]"]
end

subgraph group_node["Node backend"]
  node_nodebackend["Express MTProto backend<br/>[server.js]"]
end

node_user(("User"))
node_telegramcloud{{"Telegram Cloud"}}

node_user -->|"submits link"| node_webapp
node_webapp -->|"calls API"| node_pythonapp
node_webapp -->|"calls API"| node_nodebackend
node_webapp -.->|"uses offline shell"| node_webpwa
node_user -.->|"opens app"| node_activity
node_activity -->|"shows"| node_screen
node_screen -->|"invokes actions"| node_viewmodel
node_viewmodel -->|"updates"| node_uistate
node_viewmodel -->|"calls"| node_contract
node_viewmodel -->|"constructs"| node_repository
node_repository -->|"requests"| node_api
node_network -->|"configures"| node_api
node_repository -->|"maps and reports"| node_domain
node_screen -->|"renders metadata and progress"| node_domain
node_screen -->|"uses colors"| node_androidtheme
node_api -->|"HTTP requests"| node_pythonapp
node_api -->|"HTTP requests"| node_nodebackend
node_pythonapp -->|"mounts routes"| node_routes
node_pythonapp -->|"starts and stops"| node_telegram
node_pythonapp -->|"reads settings"| node_config
node_pythonapp -->|"serves static client"| node_webapp
node_routes -->|"resolves and streams"| node_telegram
node_routes -->|"builds stream URL"| node_config
node_routes -->|"validates and responds"| node_schemas
node_telegram -->|"uses credentials and chunk size"| node_config
node_telegram -->|"MTProto access"| node_telegramcloud
node_nodebackend -->|"MTProto access"| node_telegramcloud
node_pythonapp -.->|"serves downloads"| node_user

click node_webapp "https://github.com/vengatz-git/file-downloader/blob/main/web/app.js"
click node_webpwa "https://github.com/vengatz-git/file-downloader/blob/main/web/sw.js"
click node_activity "https://github.com/vengatz-git/file-downloader/blob/main/android/app/src/main/java/com/tgdownloader/app/MainActivity.kt"
click node_screen "https://github.com/vengatz-git/file-downloader/blob/main/android/app/src/main/java/com/tgdownloader/app/ui/screen/MainScreen.kt"
click node_viewmodel "https://github.com/vengatz-git/file-downloader/blob/main/android/app/src/main/java/com/tgdownloader/app/ui/viewmodel/MainViewModel.kt"
click node_uistate "https://github.com/vengatz-git/file-downloader/blob/main/android/app/src/main/java/com/tgdownloader/app/ui/viewmodel/MainUiState.kt"
click node_domain "https://github.com/vengatz-git/file-downloader/blob/main/android/app/src/main/java/com/tgdownloader/app/domain/model/FileMetadata.kt"
click node_repository "https://github.com/vengatz-git/file-downloader/blob/main/android/app/src/main/java/com/tgdownloader/app/data/repository/TelegramRepositoryImpl.kt"
click node_contract "https://github.com/vengatz-git/file-downloader/blob/main/android/app/src/main/java/com/tgdownloader/app/domain/repository/TelegramRepository.kt"
click node_api "https://github.com/vengatz-git/file-downloader/blob/main/android/app/src/main/java/com/tgdownloader/app/data/remote/TelegramApiService.kt"
click node_network "https://github.com/vengatz-git/file-downloader/blob/main/android/app/src/main/java/com/tgdownloader/app/data/remote/NetworkModule.kt"
click node_androidtheme "https://github.com/vengatz-git/file-downloader/blob/main/android/app/src/main/java/com/tgdownloader/app/ui/theme/Color.kt"
click node_pythonapp "https://github.com/vengatz-git/file-downloader/blob/main/backend/app/main.py"
click node_routes "https://github.com/vengatz-git/file-downloader/blob/main/backend/app/api/routes.py"
click node_telegram "https://github.com/vengatz-git/file-downloader/blob/main/backend/app/core/telegram.py"
click node_config "https://github.com/vengatz-git/file-downloader/blob/main/backend/app/core/config.py"
click node_schemas "https://github.com/vengatz-git/file-downloader/blob/main/backend/app/schemas/file.py"
click node_nodebackend "https://github.com/vengatz-git/file-downloader/blob/main/backend-node/server.js"

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_webapp,node_webpwa,node_user toneBlue
class node_activity,node_screen,node_viewmodel,node_uistate,node_domain,node_repository,node_contract,node_api,node_network,node_androidtheme toneAmber
class node_pythonapp,node_routes,node_telegram,node_config,node_schemas toneMint
class node_nodebackend toneRose
class node_telegramcloud toneIndigo
```

## Components

### Web client

- [Web downloader](https://github.com/vengatz-git/file-downloader/blob/main/web/app.js): `web/app.js`
- [PWA shell](https://github.com/vengatz-git/file-downloader/blob/main/web/sw.js): `web/sw.js`

### Android client

- [App entry](https://github.com/vengatz-git/file-downloader/blob/main/android/app/src/main/java/com/tgdownloader/app/MainActivity.kt): `android/app/src/main/java/com/tgdownloader/app/MainActivity.kt`
- [Downloader screen](https://github.com/vengatz-git/file-downloader/blob/main/android/app/src/main/java/com/tgdownloader/app/ui/screen/MainScreen.kt): `android/app/src/main/java/com/tgdownloader/app/ui/screen/MainScreen.kt`
- [Download state](https://github.com/vengatz-git/file-downloader/blob/main/android/app/src/main/java/com/tgdownloader/app/ui/viewmodel/MainViewModel.kt): `android/app/src/main/java/com/tgdownloader/app/ui/viewmodel/MainViewModel.kt`
- [UI state](https://github.com/vengatz-git/file-downloader/blob/main/android/app/src/main/java/com/tgdownloader/app/ui/viewmodel/MainUiState.kt): `android/app/src/main/java/com/tgdownloader/app/ui/viewmodel/MainUiState.kt`
- [File and progress models](https://github.com/vengatz-git/file-downloader/blob/main/android/app/src/main/java/com/tgdownloader/app/domain/model/FileMetadata.kt): `android/app/src/main/java/com/tgdownloader/app/domain/model/FileMetadata.kt`
- [Download repository](https://github.com/vengatz-git/file-downloader/blob/main/android/app/src/main/java/com/tgdownloader/app/data/repository/TelegramRepositoryImpl.kt): `android/app/src/main/java/com/tgdownloader/app/data/repository/TelegramRepositoryImpl.kt`
- [Repository contract](https://github.com/vengatz-git/file-downloader/blob/main/android/app/src/main/java/com/tgdownloader/app/domain/repository/TelegramRepository.kt): `android/app/src/main/java/com/tgdownloader/app/domain/repository/TelegramRepository.kt`
- [HTTP API client](https://github.com/vengatz-git/file-downloader/blob/main/android/app/src/main/java/com/tgdownloader/app/data/remote/TelegramApiService.kt): `android/app/src/main/java/com/tgdownloader/app/data/remote/TelegramApiService.kt`
- [Network setup](https://github.com/vengatz-git/file-downloader/blob/main/android/app/src/main/java/com/tgdownloader/app/data/remote/NetworkModule.kt): `android/app/src/main/java/com/tgdownloader/app/data/remote/NetworkModule.kt`
- [Compose theme](https://github.com/vengatz-git/file-downloader/blob/main/android/app/src/main/java/com/tgdownloader/app/ui/theme/Color.kt): `android/app/src/main/java/com/tgdownloader/app/ui/theme/Color.kt`

### Python backend

- [FastAPI app](https://github.com/vengatz-git/file-downloader/blob/main/backend/app/main.py): `backend/app/main.py`
- [Resolve and stream routes](https://github.com/vengatz-git/file-downloader/blob/main/backend/app/api/routes.py): `backend/app/api/routes.py`
- [Telethon manager](https://github.com/vengatz-git/file-downloader/blob/main/backend/app/core/telegram.py): `backend/app/core/telegram.py`
- [Backend settings](https://github.com/vengatz-git/file-downloader/blob/main/backend/app/core/config.py): `backend/app/core/config.py`
- [API schemas](https://github.com/vengatz-git/file-downloader/blob/main/backend/app/schemas/file.py): `backend/app/schemas/file.py`

### Node backend

- [Express MTProto backend](https://github.com/vengatz-git/file-downloader/blob/main/backend-node/server.js): `backend-node/server.js`

### Other components

- **User**
- **Telegram Cloud**

## Connections

- User → Web downloader: submits link (evidence: `README.md`)
- Web downloader → FastAPI app: calls API (evidence: `README.md`)
- Web downloader → Express MTProto backend: calls API (evidence: `README.md`)
- Web downloader → PWA shell: uses offline shell
- User → App entry: opens app
- App entry → Downloader screen: shows (evidence: `android/app/src/main/java/com/tgdownloader/app/MainActivity.kt`)
- Downloader screen → Download state: invokes actions (evidence: `android/app/src/main/java/com/tgdownloader/app/ui/screen/MainScreen.kt`)
- Download state → UI state: updates (evidence: `android/app/src/main/java/com/tgdownloader/app/ui/viewmodel/MainViewModel.kt`)
- Download state → Repository contract: calls (evidence: `android/app/src/main/java/com/tgdownloader/app/ui/viewmodel/MainViewModel.kt`)
- Download state → Download repository: constructs (evidence: `android/app/src/main/java/com/tgdownloader/app/ui/viewmodel/MainViewModel.kt`)
- Download repository → HTTP API client: requests (evidence: `android/app/src/main/java/com/tgdownloader/app/data/repository/TelegramRepositoryImpl.kt`)
- Network setup → HTTP API client: configures (evidence: `android/app/src/main/java/com/tgdownloader/app/data/remote/NetworkModule.kt`)
- Download repository → File and progress models: maps and reports (evidence: `android/app/src/main/java/com/tgdownloader/app/data/repository/TelegramRepositoryImpl.kt`)
- Downloader screen → File and progress models: renders metadata and progress (evidence: `android/app/src/main/java/com/tgdownloader/app/ui/screen/MainScreen.kt`)
- Downloader screen → Compose theme: uses colors (evidence: `android/app/src/main/java/com/tgdownloader/app/ui/screen/MainScreen.kt`)
- HTTP API client → FastAPI app: HTTP requests (evidence: `README.md`)
- HTTP API client → Express MTProto backend: HTTP requests (evidence: `README.md`)
- FastAPI app → Resolve and stream routes: mounts routes (evidence: `backend/app/main.py`)
- FastAPI app → Telethon manager: starts and stops (evidence: `backend/app/main.py`)
- FastAPI app → Backend settings: reads settings (evidence: `backend/app/main.py`)
- FastAPI app → Web downloader: serves static client (evidence: `backend/app/main.py`)
- Resolve and stream routes → Telethon manager: resolves and streams (evidence: `backend/app/api/routes.py`)
- Resolve and stream routes → Backend settings: builds stream URL (evidence: `backend/app/api/routes.py`)
- Resolve and stream routes → API schemas: validates and responds (evidence: `backend/app/api/routes.py`)
- Telethon manager → Backend settings: uses credentials and chunk size (evidence: `backend/app/core/telegram.py`)
- Telethon manager → Telegram Cloud: MTProto access (evidence: `README.md`)
- Express MTProto backend → Telegram Cloud: MTProto access (evidence: `README.md`)
- FastAPI app → User: serves downloads
