# caamer20/telegram-drive-forvpns architecture

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

- Interactive diagram: https://gitdiagram.com/caamer20/telegram-drive-forvpns
- Repository: https://github.com/caamer20/telegram-drive-forvpns

## Overview

1. **High-level shape**
   - This is a **desktop app** built with **Tauri**: a **React/TypeScript frontend** in `app/src` and a **Rust backend** in `app/src-tauri`.
   - The app’s core purpose is to present **Telegram cloud storage** as a local file-drive experience, using Telegram’s own servers as the only remote backend.

2. **Primary external boundary: Telegram**
   - The only major external service is the **Telegram API**.
   - The README makes clear that the app stores data in Telegram “Saved Messages” and private channels, which it treats as **folders**.
   - The Rust side, via **Grammers**, is responsible for all actual Telegram authentication, browsing, upload/download, and media fetching.

3. **Frontend shell and app composition**
   - `app/src/main.tsx` and `app/src/App.tsx` form the UI entry point.
   - The UI is organized around a **dashboard** experience, with separate flows for **authentication** and **file management**.
   - Supporting UI concerns are split into components such as `ThemeToggle`, `UpdateBanner`, `ErrorBoundary`, and `AuthWizard`.

4. **Dashboard subsystem**
   - The main workspace is under `app/src/components/dashboard`.
   - This includes the file explorer, file list/grid items, sidebar, top bar, queues, modals, drag-drop overlay, preview modal, and media player.
   - Architecturally, this is the presentation layer for browsing Telegram-backed folders, uploading files, previewing media, and managing operations in progress.

5. **Frontend state and interaction layer**
   - Cross-cutting UI state is handled through contexts such as `ThemeContext`, `ConfirmContext`, and `DropZoneContext`.
   - Behavior is further split into hooks like `useFileUpload`, `useFileDownload`, `useFileOperations`, `useFileDrop`, `useKeyboardShortcuts`, `useNetworkStatus`, `useTelegramConnection`, and `useUpdateCheck`.
   - These hooks are the frontend’s bridge to Tauri commands and to app-wide operational state like connectivity, transfer progress, and update availability.

6. **Rust backend command boundary**
   - The backend is organized around Tauri command modules in `app/src-tauri/src/commands`.
   - The command groups show the major backend domains: `auth`, `fs`, `network`, `preview`, `menu`, `retry`, and `utils`.
   - This indicates a clean split where the frontend asks for actions, and the Rust layer performs Telegram and OS-native work.

7. **Authentication and session establishment**
   - Authentication is a distinct subsystem, reflected in `commands/auth.rs` and the frontend `AuthWizard`.
   - The readme notes resilient auth behavior, including retries around initial connection and `get_me` checks.
   - In the architecture diagram, this is the first major lifecycle step: user credentials/API info are entered in the UI, sent to Rust, and used to establish a Telegram session locally.

8. **File system / drive abstraction**
   - The file-management core lives in `commands/fs.rs` plus the dashboard explorer/list components.
   - Telegram entities are abstracted into a drive-like model: folders, files, moving items, and folder creation all map onto Telegram objects.
   - `models.rs` likely defines the shared data structures passed between backend and frontend for files, folders, transfers, and status.

9. **Transfer pipeline: upload, download, preview**
   - The app has explicit UI queues for uploads and downloads, suggesting asynchronous transfer orchestration rather than simple request/response.
   - `commands/preview.rs` and `MediaPlayer`/`PreviewModal` show that media handling is a first-class flow: the backend fetches or resolves the file, while the frontend renders previews and playback.
   - `bandwidth.rs` and `BandwidthWidget` indicate live transfer-rate tracking as part of the user experience.

10. **Network resilience subsystem**
    - This fork adds a strong backend network-resilience layer centered on `commands/network.rs` and `commands/retry.rs`.
    - The README highlights multi-DC fallback, longer timeouts, exponential backoff, flood-wait handling, and recovery from broken pipes/EOFs.
    - For the diagram, this is an important boundary between the app and Telegram because it affects every remote call, especially under VPN conditions.

11. **Connection monitoring and adaptive polling**
    - The frontend includes `useNetworkStatus` and `useTelegramConnection`, showing that the app actively monitors connection health.
    - The README describes adaptive polling that slows down when necessary to reduce VPN traffic.
    - This creates a feedback loop: network state influences polling cadence and operational retries across the UI/backend boundary.

12. **Native desktop integration**
    - `commands/menu.rs` implies Tauri-side native menu/window integration.
    - `app/src-tauri/src/main.rs`, `lib.rs`, and `server.rs` define the native application host, while `tauri.conf.json` and `capabilities/default.json` define app permissions and runtime capabilities.
    - This is the layer that turns the web UI into a desktop application with OS-level affordances like menus and update behavior.

13. **Build, packaging, and update lifecycle**
    - The repository uses **Vite** for the frontend and **Cargo/Tauri** for the backend.
    - GitHub Actions in `.github/workflows` indicate automated CI/release pipelines, and `UpdateBanner` plus `useUpdateCheck` show the app is designed for in-app update awareness.
    - The `src-tauri/icons` tree and platform-specific assets point to cross-platform packaging for Windows, macOS, and Linux.

14. **Key architectural takeaway**
    - The simplest diagram is: **React UI → Tauri command bridge → Rust Telegram client layer → Telegram API**, with local contexts/hooks managing UI state and the Rust layer handling auth, file operations, previews, retries, and native integration.
    - The most important design boundary is between **local desktop state** and **remote Telegram-backed storage**, because the entire product is a drive abstraction over Telegram rather than a conventional file server.

Main entry points: [`app/src-tauri/src/commands/mod.rs`](https://github.com/caamer20/telegram-drive-forvpns/blob/main/app/src-tauri/src/commands/mod.rs) (Commands), [`app/src/components/Dashboard.tsx`](https://github.com/caamer20/telegram-drive-forvpns/blob/main/app/src/components/Dashboard.tsx) (Dashboard), [`app/src/App.tsx`](https://github.com/caamer20/telegram-drive-forvpns/blob/main/app/src/App.tsx) (App shell), [`app/src-tauri/src/commands/fs.rs`](https://github.com/caamer20/telegram-drive-forvpns/blob/main/app/src-tauri/src/commands/fs.rs) (FS cmd)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_main_entry["App entry<br/>React bootstrap<br/>[main.tsx]"]
  node_app_shell["App shell<br/>React layout<br/>[App.tsx]"]
  node_auth_wizard["Auth wizard<br/>auth flow<br/>[AuthWizard.tsx]"]
  node_dashboard_shell["Dashboard<br/>workspace<br/>[Dashboard.tsx]"]
  node_theme_state["UI state<br/>contexts<br/>[ThemeContext.tsx]"]
  node_drop_state["Drop state<br/>drop context"]
  node_file_ops_hooks["File hooks"]
  node_dashboard_explorer["Explorer<br/>file browser<br/>[FileExplorer.tsx]"]
  node_dashboard_panels["Dashboard panels<br/>ui panels<br/>[Sidebar.tsx]"]
  node_transfer_ui["Transfers<br/>queues<br/>[UploadQueue.tsx]"]
  node_preview_ui["Preview<br/>[PreviewModal.tsx]"]
end

subgraph group_backend["Backend"]
  node_rust_host["Tauri host<br/>desktop host<br/>[main.rs]"]
  node_tauri_commands["Commands<br/>command bridge<br/>[mod.rs]"]
  node_auth_cmd["Auth cmd<br/>telegram auth<br/>[auth.rs]"]
  node_fs_cmd["FS cmd<br/>drive abstraction<br/>[fs.rs]"]
  node_network_cmd["Network cmd<br/>resilience<br/>[network.rs]"]
  node_preview_cmd["Preview cmd<br/>media fetch<br/>[preview.rs]"]
  node_menu_cmd["Menu cmd<br/>native integration<br/>[menu.rs]"]
  node_retry_cmd["Retry cmd<br/>recovery<br/>[retry.rs]"]
  node_models["Models<br/>shared types<br/>[models.rs]"]
  node_bandwidth["Bandwidth<br/>telemetry<br/>[bandwidth.rs]"]
end

subgraph group_infra["Build & Release"]
  node_tauri_config["Tauri config<br/>runtime config<br/>[tauri.conf.json]"]
  node_ci_release["CI release<br/>automation<br/>[release.yml]"]
end

subgraph group_external["External"]
  node_telegram_api(("Telegram API<br/>remote service"))
end

node_main_entry -->|"boots"| node_app_shell
node_app_shell -->|"auth flow"| node_auth_wizard
node_app_shell -->|"workspace"| node_dashboard_shell
node_app_shell -->|"provides"| node_theme_state
node_app_shell -->|"provides"| node_drop_state
node_dashboard_shell -->|"contains"| node_dashboard_explorer
node_dashboard_shell -->|"contains"| node_dashboard_panels
node_dashboard_shell -->|"shows"| node_transfer_ui
node_dashboard_shell -->|"opens"| node_preview_ui
node_dashboard_shell -->|"uses"| node_file_ops_hooks
node_file_ops_hooks -->|"calls"| node_tauri_commands
node_auth_wizard -->|"authenticates"| node_auth_cmd
node_dashboard_explorer -->|"browses"| node_fs_cmd
node_dashboard_panels -->|"manages files"| node_fs_cmd
node_transfer_ui -->|"tracks"| node_bandwidth
node_transfer_ui -->|"uploads/downloads"| node_fs_cmd
node_preview_ui -->|"resolves media"| node_preview_cmd
node_tauri_commands -->|"groups"| node_auth_cmd
node_tauri_commands -->|"groups"| node_fs_cmd
node_tauri_commands -->|"groups"| node_network_cmd
node_tauri_commands -->|"groups"| node_preview_cmd
node_tauri_commands -->|"groups"| node_menu_cmd
node_tauri_commands -->|"groups"| node_retry_cmd
node_tauri_commands -->|"shares types"| node_models
node_auth_cmd -->|"auths with"| node_telegram_api
node_fs_cmd -->|"reads/writes"| node_telegram_api
node_network_cmd -->|"hardens calls"| node_telegram_api
node_preview_cmd -->|"fetches media"| node_telegram_api
node_retry_cmd -->|"recovers"| node_telegram_api
node_rust_host -->|"hosts"| node_tauri_commands
node_rust_host -->|"configured by"| node_tauri_config
node_ci_release -.->|"builds"| node_rust_host
node_ci_release -.->|"builds"| node_app_shell

click node_main_entry "https://github.com/caamer20/telegram-drive-forvpns/blob/main/app/src/main.tsx"
click node_app_shell "https://github.com/caamer20/telegram-drive-forvpns/blob/main/app/src/App.tsx"
click node_auth_wizard "https://github.com/caamer20/telegram-drive-forvpns/blob/main/app/src/components/AuthWizard.tsx"
click node_dashboard_shell "https://github.com/caamer20/telegram-drive-forvpns/blob/main/app/src/components/Dashboard.tsx"
click node_theme_state "https://github.com/caamer20/telegram-drive-forvpns/blob/main/app/src/context/ThemeContext.tsx"
click node_drop_state "https://github.com/caamer20/telegram-drive-forvpns/blob/main/app/src/contexts/DropZoneContext.tsx"
click node_file_ops_hooks "https://github.com/caamer20/telegram-drive-forvpns/blob/main/app/src/hooks/useFileOperations.ts"
click node_dashboard_explorer "https://github.com/caamer20/telegram-drive-forvpns/blob/main/app/src/components/dashboard/FileExplorer.tsx"
click node_dashboard_panels "https://github.com/caamer20/telegram-drive-forvpns/blob/main/app/src/components/dashboard/Sidebar.tsx"
click node_transfer_ui "https://github.com/caamer20/telegram-drive-forvpns/blob/main/app/src/components/dashboard/UploadQueue.tsx"
click node_preview_ui "https://github.com/caamer20/telegram-drive-forvpns/blob/main/app/src/components/dashboard/PreviewModal.tsx"
click node_rust_host "https://github.com/caamer20/telegram-drive-forvpns/blob/main/app/src-tauri/src/main.rs"
click node_tauri_commands "https://github.com/caamer20/telegram-drive-forvpns/blob/main/app/src-tauri/src/commands/mod.rs"
click node_auth_cmd "https://github.com/caamer20/telegram-drive-forvpns/blob/main/app/src-tauri/src/commands/auth.rs"
click node_fs_cmd "https://github.com/caamer20/telegram-drive-forvpns/blob/main/app/src-tauri/src/commands/fs.rs"
click node_network_cmd "https://github.com/caamer20/telegram-drive-forvpns/blob/main/app/src-tauri/src/commands/network.rs"
click node_preview_cmd "https://github.com/caamer20/telegram-drive-forvpns/blob/main/app/src-tauri/src/commands/preview.rs"
click node_menu_cmd "https://github.com/caamer20/telegram-drive-forvpns/blob/main/app/src-tauri/src/commands/menu.rs"
click node_retry_cmd "https://github.com/caamer20/telegram-drive-forvpns/blob/main/app/src-tauri/src/commands/retry.rs"
click node_models "https://github.com/caamer20/telegram-drive-forvpns/blob/main/app/src-tauri/src/models.rs"
click node_bandwidth "https://github.com/caamer20/telegram-drive-forvpns/blob/main/app/src-tauri/src/bandwidth.rs"
click node_tauri_config "https://github.com/caamer20/telegram-drive-forvpns/blob/main/app/src-tauri/tauri.conf.json"
click node_ci_release "https://github.com/caamer20/telegram-drive-forvpns/blob/main/.github/workflows/release.yml"

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_entry,node_app_shell,node_auth_wizard,node_dashboard_shell,node_theme_state,node_drop_state,node_file_ops_hooks,node_dashboard_explorer,node_dashboard_panels,node_transfer_ui,node_preview_ui toneBlue
class node_rust_host,node_tauri_commands,node_auth_cmd,node_fs_cmd,node_network_cmd,node_preview_cmd,node_menu_cmd,node_retry_cmd,node_models,node_bandwidth toneAmber
class node_tauri_config,node_ci_release toneMint
class node_telegram_api toneRose
```

## Components

### Frontend

React/TypeScript desktop UI and interaction state.

- [App entry](https://github.com/caamer20/telegram-drive-forvpns/blob/main/app/src/main.tsx): React bootstrap · Main UI entrypoint and root composition. · `app/src/main.tsx`
- [App shell](https://github.com/caamer20/telegram-drive-forvpns/blob/main/app/src/App.tsx): React layout · Top-level application composition and routing between auth and dashboard. · `app/src/App.tsx`
- [Auth wizard](https://github.com/caamer20/telegram-drive-forvpns/blob/main/app/src/components/AuthWizard.tsx): auth flow · Credential setup and first-time Telegram session entry. · `app/src/components/AuthWizard.tsx`
- [Dashboard](https://github.com/caamer20/telegram-drive-forvpns/blob/main/app/src/components/Dashboard.tsx): workspace · Main browsing workspace for Telegram-backed storage. · `app/src/components/Dashboard.tsx`
- [UI state](https://github.com/caamer20/telegram-drive-forvpns/blob/main/app/src/context/ThemeContext.tsx): contexts · Cross-cutting theme, confirmation, and drop-zone state. · `app/src/context/ThemeContext.tsx`
- [Drop state](https://github.com/caamer20/telegram-drive-forvpns/blob/main/app/src/contexts/DropZoneContext.tsx): drop context · Drag-and-drop coordination for file ingress and blocking. · `app/src/contexts/DropZoneContext.tsx`
- [File hooks](https://github.com/caamer20/telegram-drive-forvpns/blob/main/app/src/hooks/useFileOperations.ts): hooks · Upload, download, operations, keyboard, network, connection, and update bridge hooks. · `app/src/hooks/useFileOperations.ts`
- [Explorer](https://github.com/caamer20/telegram-drive-forvpns/blob/main/app/src/components/dashboard/FileExplorer.tsx): file browser · Folder browsing, list/grid presentation, and selection entry point. · `app/src/components/dashboard/FileExplorer.tsx`
- [Dashboard panels](https://github.com/caamer20/telegram-drive-forvpns/blob/main/app/src/components/dashboard/Sidebar.tsx): ui panels · Sidebar, top bar, file items, empty state, context menu, and folder move dialog. · `app/src/components/dashboard/Sidebar.tsx`
- [Transfers](https://github.com/caamer20/telegram-drive-forvpns/blob/main/app/src/components/dashboard/UploadQueue.tsx): queues · Upload and download queues plus bandwidth visibility. · `app/src/components/dashboard/UploadQueue.tsx`
- [Preview](https://github.com/caamer20/telegram-drive-forvpns/blob/main/app/src/components/dashboard/PreviewModal.tsx): media preview · Preview modal and media playback for Telegram files. · `app/src/components/dashboard/PreviewModal.tsx`

### Backend

Tauri/Rust command layer and Telegram client integration.

- [Tauri host](https://github.com/caamer20/telegram-drive-forvpns/blob/main/app/src-tauri/src/main.rs): desktop host · Native application host and runtime entry points. · `app/src-tauri/src/main.rs`
- [Commands](https://github.com/caamer20/telegram-drive-forvpns/blob/main/app/src-tauri/src/commands/mod.rs): command bridge · Tauri command modules coordinating frontend requests. · `app/src-tauri/src/commands/mod.rs`
- [Auth cmd](https://github.com/caamer20/telegram-drive-forvpns/blob/main/app/src-tauri/src/commands/auth.rs): telegram auth · Session creation, login, and connection validation. · `app/src-tauri/src/commands/auth.rs`
- [FS cmd](https://github.com/caamer20/telegram-drive-forvpns/blob/main/app/src-tauri/src/commands/fs.rs): drive abstraction · Telegram-backed folder and file operations. · `app/src-tauri/src/commands/fs.rs`
- [Network cmd](https://github.com/caamer20/telegram-drive-forvpns/blob/main/app/src-tauri/src/commands/network.rs): resilience · Fallback, timeout, and retry behavior for Telegram calls. · `app/src-tauri/src/commands/network.rs`
- [Preview cmd](https://github.com/caamer20/telegram-drive-forvpns/blob/main/app/src-tauri/src/commands/preview.rs): media fetch · Backend resolution and fetching for previews and playback. · `app/src-tauri/src/commands/preview.rs`
- [Menu cmd](https://github.com/caamer20/telegram-drive-forvpns/blob/main/app/src-tauri/src/commands/menu.rs): native integration · Desktop menu and window integration. · `app/src-tauri/src/commands/menu.rs`
- [Retry cmd](https://github.com/caamer20/telegram-drive-forvpns/blob/main/app/src-tauri/src/commands/retry.rs): recovery · Explicit retry and recovery helpers for remote operations. · `app/src-tauri/src/commands/retry.rs`
- [Models](https://github.com/caamer20/telegram-drive-forvpns/blob/main/app/src-tauri/src/models.rs): shared types · Shared data structures passed across the Tauri boundary. · `app/src-tauri/src/models.rs`
- [Bandwidth](https://github.com/caamer20/telegram-drive-forvpns/blob/main/app/src-tauri/src/bandwidth.rs): telemetry · Transfer-rate tracking used by the backend and widget. · `app/src-tauri/src/bandwidth.rs`

### Build & Release

Packaging, configuration, and automation.

- [Tauri config](https://github.com/caamer20/telegram-drive-forvpns/blob/main/app/src-tauri/tauri.conf.json): runtime config · Capabilities and application configuration for the desktop shell. · `app/src-tauri/tauri.conf.json`
- [CI release](https://github.com/caamer20/telegram-drive-forvpns/blob/main/.github/workflows/release.yml): automation · Build and release workflows. · `.github/workflows/release.yml`

### External

Remote service boundary.

- **Telegram API**: remote service · Only major external backend for storage, auth, browsing, and transfers.

## Connections

- App entry → App shell: boots · React boots the application shell.
- App shell → Auth wizard: auth flow · Shell routes unauthenticated users into setup.
- App shell → Dashboard: workspace · Shell renders the main dashboard after login.
- App shell → UI state: provides · App composes global UI state providers.
- App shell → Drop state: provides · App composes drag-drop coordination state.
- Dashboard → Explorer: contains · Dashboard centers on file browsing.
- Dashboard → Dashboard panels: contains · Dashboard uses sidebars, bars, and item views.
- Dashboard → Transfers: shows · Dashboard surfaces transfer queues and bandwidth.
- Dashboard → Preview: opens · Dashboard can present file previews and playback.
- Dashboard → File hooks: uses · Dashboard interaction is driven by operational hooks.
- File hooks → Commands: calls · Frontend hooks invoke backend commands.
- Auth wizard → Auth cmd: authenticates · Authentication setup is executed by Rust commands.
- Explorer → FS cmd: browses · Explorer reads and manipulates the Telegram-backed file model.
- Dashboard panels → FS cmd: manages files · Sidebar and item actions trigger folder and file operations.
- Transfers → Bandwidth: tracks · Queues expose throughput and progress telemetry.
- Transfers → FS cmd: uploads/downloads · Transfers are executed by backend file commands.
- Preview → Preview cmd: resolves media · Preview presentation depends on backend fetch/resolve logic.
- Commands → Auth cmd: groups · Command layer includes auth domain.
- Commands → FS cmd: groups · Command layer includes file-system domain.
- Commands → Network cmd: groups · Command layer includes network resilience domain.
- Commands → Preview cmd: groups · Command layer includes preview domain.
- Commands → Menu cmd: groups · Command layer includes native menu integration.
- Commands → Retry cmd: groups · Command layer includes retry helpers.
- Commands → Models: shares types · Commands and frontend exchange shared data models.
- Auth cmd → Telegram API: auths with · Authentication is performed against Telegram.
- FS cmd → Telegram API: reads/writes · File abstraction maps onto Telegram storage.
- Network cmd → Telegram API: hardens calls · Network layer wraps Telegram requests with fallback and retry.
- Preview cmd → Telegram API: fetches media · Preview content is resolved from Telegram.
- Retry cmd → Telegram API: recovers · Retry logic helps remote operations survive transient failures.
- Tauri host → Commands: hosts · Native app host registers and serves commands.
- Tauri host → Tauri config: configured by · Runtime behavior is shaped by Tauri configuration.
- CI release → Tauri host: builds · Automation packages the desktop backend.
- CI release → App shell: builds · Automation packages the frontend UI.
