# cloudflarehackers/tg-webapp-proxy architecture

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

- Interactive diagram: https://gitdiagram.com/cloudflarehackers/tg-webapp-proxy
- Repository: https://github.com/cloudflarehackers/tg-webapp-proxy

## Overview

#### Purpose and Entry Points
This is a browser-only Telegram MTProto client for bot-based file retrieval/messaging and authenticated user accounts. Vite serves and bundles the SPA from `index.html`, which loads `src/main.js`. Cloudflare Pages deployment is configured by `wrangler.toml`; an optional same-origin proxy endpoint is implemented at `functions/api/[[path]].js`.

#### Application Composition
`src/main.js` is the top-level mode router and bot-mode UI/controller. It initializes shared browser support, binds UI events, manages bot state, and delegates Telegram operations. User-mode rendering and interactions are separated into `src/user-mode.js`, while protocol-facing implementations are in `src/telegram-client.js` and `src/user-client.js`.

#### Bot Client Flow
`src/telegram-client.js` defines the bot-oriented Telegram client: bot-token authentication, message reception/replies, Telegram-link retrieval, and file download orchestration. Parsed links from `src/link-parser.js` identify target messages/media. Large files are partitioned into ranges, downloaded by multiple Telegram DC connections with retries/migration handling, then assembled; small files use the standard media path.

#### User Account Flow
`src/user-client.js` owns phone login, 2FA continuation, account/session isolation, dialogs, message history, real-time updates, sending, and user-media downloads. `src/user-mode.js` presents account switching, chat browsing/filtering, infinite message loading, reply state, media views, and the sequential download queue. The UI calls client operations rather than directly invoking MTProto.

#### Protocol and Browser Adaptation
Teleproto runs entirely in the browser but expects Node-style facilities. `src/polyfills.js` establishes global compatibility before client loading. `src/shims/browser-session.js` persists teleproto session/auth/DC/entity state through `localStorage`, and `src/shims/promised-web-sockets.js` replaces socket transport while mapping Telegram DCs to WebSocket hostnames. Crypto and compressed MTProto payload support are provided by `src/shims/crypto.js` and `src/shims/zlib.js`; Vite aliases/bundles these boundaries in `vite.config.js`.

#### Connectivity and Proxy Boundary
By default, MTProto WebSockets connect from the browser to Telegram DC WebSocket hosts. `src/proxy-hook.js` globally intercepts `WebSocket` construction and rewrites Telegram URLs when proxy settings are enabled, without coupling teleproto to proxy logic. The optional Cloudflare Pages fallback at `functions/api/[[path]].js` validates allowed Telegram targets and proxies HTTP/WebSocket traffic; external Cloudflare Worker/Durable Object infrastructure may alternatively relay encrypted frames.

#### Persistence and Settings
`src/settings.js` owns mode-specific preferences plus shared proxy configuration in `localStorage`. `src/db.js` is the IndexedDB boundary for bot conversation history and file metadata, allowing retained messages/files to be reconstructed after refresh. Sessions, credentials, account metadata, and UI settings remain local to the browser; IndexedDB is not the primary user-session store.

#### Material Runtimes and Services
The runtime is a Vite-built ES2020 browser SPA using teleproto/MTProto, Web Crypto plus custom AES support, native WebSocket, `localStorage`, and IndexedDB. It communicates directly with Telegram servers or optionally through Cloudflare Pages/Workers proxy infrastructure. `package.json` defines the browser dependency/build surface, and `vite.config.js` controls browser-targeted module replacement and chunking.

Main entry points: [`src/main.js`](https://github.com/cloudflarehackers/tg-webapp-proxy/blob/main/src/main.js) (Mode router & bot UI), [`vite.config.js`](https://github.com/cloudflarehackers/tg-webapp-proxy/blob/main/vite.config.js) (Vite build boundary), [`src/user-mode.js`](https://github.com/cloudflarehackers/tg-webapp-proxy/blob/main/src/user-mode.js) (User-mode UI), [`src/telegram-client.js`](https://github.com/cloudflarehackers/tg-webapp-proxy/blob/main/src/telegram-client.js) (Bot Telegram client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_spa["Browser SPA"]
  node_index["SPA entry page<br/>Vite entry<br/>[index.html]"]
  node_main["Mode router &amp; bot UI<br/>application controller<br/>[main.js]"]
  node_user_ui["User-mode UI<br/>account UI controller<br/>[user-mode.js]"]
  node_settings["Settings<br/>preferences store<br/>[settings.js]"]
  node_vite["Vite build boundary<br/>browser bundler<br/>[vite.config.js]"]
end

subgraph group_telegram["Telegram integration"]
  node_bot_client["Bot Telegram client<br/>MTProto bot client<br/>[telegram-client.js]"]
  node_link_parser["Telegram link parser<br/>[link-parser.js]"]
  node_user_client["User Telegram client<br/>MTProto account client<br/>[user-client.js]"]
  node_teleproto{{"teleproto / MTProto<br/>protocol runtime"}}
  node_telegram_dc{{"Telegram DCs<br/>external MTProto service"}}
end

subgraph group_browser["Browser adapters &amp; storage"]
  node_polyfills["Compatibility bootstrap<br/>browser polyfills<br/>[polyfills.js]"]
  node_session_shim["Browser session shim<br/>localStorage session adapter<br/>[browser-session.js]"]
  node_socket_shim["WebSocket transport shim<br/>teleproto socket adapter"]
  node_crypto_zlib["Crypto &amp; compression shims<br/>protocol adapters<br/>[crypto.js]"]
  node_local_storage[("Browser localStorage<br/>browser persistence")]
  node_indexed_db[("Bot history database<br/>IndexedDB boundary<br/>[db.js]")]
end

subgraph group_edge["Optional proxy edge"]
  node_proxy_hook["Proxy WebSocket hook<br/>connection interceptor<br/>[proxy-hook.js]"]
  node_pages_proxy["Cloudflare Pages proxy<br/>HTTP/WebSocket proxy endpoint<br/>[&#91;&#91;path&#93;&#93;.js]"]
end

node_index -->|"loads"| node_main
node_vite -->|"serves/bundles"| node_index
node_main -->|"initializes"| node_polyfills
node_main -->|"delegates bot operations"| node_bot_client
node_main -->|"routes user mode"| node_user_ui
node_main -->|"reads/writes"| node_settings
node_main -->|"restores bot state"| node_indexed_db
node_user_ui -->|"invokes account operations"| node_user_client
node_user_ui -->|"reads/writes"| node_settings
node_bot_client -->|"parses retrieval links"| node_link_parser
node_bot_client -->|"uses"| node_teleproto
node_user_client -->|"uses"| node_teleproto
node_teleproto -->|"persists state through"| node_session_shim
node_session_shim -->|"stores"| node_local_storage
node_teleproto -->|"connects through"| node_socket_shim
node_teleproto -->|"uses protocol support"| node_crypto_zlib
node_socket_shim -->|"WebSocket construction"| node_proxy_hook
node_proxy_hook -.->|"direct connection"| node_telegram_dc
node_proxy_hook -.->|"when proxy enabled"| node_pages_proxy
node_pages_proxy -->|"forwards validated traffic"| node_telegram_dc
node_settings -->|"persists preferences"| node_local_storage
node_vite -->|"aliases/bundles"| node_polyfills
node_vite -->|"aliases/bundles"| node_socket_shim

click node_index "https://github.com/cloudflarehackers/tg-webapp-proxy/blob/main/index.html"
click node_main "https://github.com/cloudflarehackers/tg-webapp-proxy/blob/main/src/main.js"
click node_user_ui "https://github.com/cloudflarehackers/tg-webapp-proxy/blob/main/src/user-mode.js"
click node_settings "https://github.com/cloudflarehackers/tg-webapp-proxy/blob/main/src/settings.js"
click node_bot_client "https://github.com/cloudflarehackers/tg-webapp-proxy/blob/main/src/telegram-client.js"
click node_link_parser "https://github.com/cloudflarehackers/tg-webapp-proxy/blob/main/src/link-parser.js"
click node_user_client "https://github.com/cloudflarehackers/tg-webapp-proxy/blob/main/src/user-client.js"
click node_polyfills "https://github.com/cloudflarehackers/tg-webapp-proxy/blob/main/src/polyfills.js"
click node_session_shim "https://github.com/cloudflarehackers/tg-webapp-proxy/blob/main/src/shims/browser-session.js"
click node_socket_shim "https://github.com/cloudflarehackers/tg-webapp-proxy/blob/main/src/shims/promised-web-sockets.js"
click node_crypto_zlib "https://github.com/cloudflarehackers/tg-webapp-proxy/blob/main/src/shims/crypto.js"
click node_indexed_db "https://github.com/cloudflarehackers/tg-webapp-proxy/blob/main/src/db.js"
click node_proxy_hook "https://github.com/cloudflarehackers/tg-webapp-proxy/blob/main/src/proxy-hook.js"
click node_pages_proxy "https://github.com/cloudflarehackers/tg-webapp-proxy/blob/main/functions/api/%5B%5Bpath%5D%5D.js"
click node_vite "https://github.com/cloudflarehackers/tg-webapp-proxy/blob/main/vite.config.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_index,node_main,node_user_ui,node_settings,node_vite toneBlue
class node_bot_client,node_link_parser,node_user_client,node_teleproto,node_telegram_dc toneAmber
class node_polyfills,node_session_shim,node_socket_shim,node_crypto_zlib,node_local_storage,node_indexed_db toneMint
class node_proxy_hook,node_pages_proxy toneRose
```

## Components

### Browser SPA

- [SPA entry page](https://github.com/cloudflarehackers/tg-webapp-proxy/blob/main/index.html): Vite entry · `index.html`
- [Mode router & bot UI](https://github.com/cloudflarehackers/tg-webapp-proxy/blob/main/src/main.js): application controller · `src/main.js`
- [User-mode UI](https://github.com/cloudflarehackers/tg-webapp-proxy/blob/main/src/user-mode.js): account UI controller · `src/user-mode.js`
- [Settings](https://github.com/cloudflarehackers/tg-webapp-proxy/blob/main/src/settings.js): preferences store · Owns mode preferences and proxy configuration. · `src/settings.js`
- [Vite build boundary](https://github.com/cloudflarehackers/tg-webapp-proxy/blob/main/vite.config.js): browser bundler · Aliases browser adapters and creates browser-targeted bundles. · `vite.config.js`

### Telegram integration

- [Bot Telegram client](https://github.com/cloudflarehackers/tg-webapp-proxy/blob/main/src/telegram-client.js): MTProto bot client · Authenticates bots, handles messages, links, and downloads. · `src/telegram-client.js`
- [Telegram link parser](https://github.com/cloudflarehackers/tg-webapp-proxy/blob/main/src/link-parser.js): link parser · `src/link-parser.js`
- [User Telegram client](https://github.com/cloudflarehackers/tg-webapp-proxy/blob/main/src/user-client.js): MTProto account client · Owns login, sessions, dialogs, updates, messages, and user-media downloads. · `src/user-client.js`
- **teleproto / MTProto**: protocol runtime · Browser-bundled MTProto protocol implementation.
- **Telegram DCs**: external MTProto service

### Browser adapters & storage

- [Compatibility bootstrap](https://github.com/cloudflarehackers/tg-webapp-proxy/blob/main/src/polyfills.js): browser polyfills · Installs Node-style globals before clients load. · `src/polyfills.js`
- [Browser session shim](https://github.com/cloudflarehackers/tg-webapp-proxy/blob/main/src/shims/browser-session.js): localStorage session adapter · Persists session, auth, DC, and entity state. · `src/shims/browser-session.js`
- [WebSocket transport shim](https://github.com/cloudflarehackers/tg-webapp-proxy/blob/main/src/shims/promised-web-sockets.js): teleproto socket adapter · Maps Telegram DCs to WebSocket hosts. · `src/shims/promised-web-sockets.js`
- [Crypto & compression shims](https://github.com/cloudflarehackers/tg-webapp-proxy/blob/main/src/shims/crypto.js): protocol adapters · `src/shims/crypto.js`
- **Browser localStorage**: browser persistence · Stores settings and user-account session state.
- [Bot history database](https://github.com/cloudflarehackers/tg-webapp-proxy/blob/main/src/db.js): IndexedDB boundary · Retains bot conversations and file metadata. · `src/db.js`

### Optional proxy edge

- [Proxy WebSocket hook](https://github.com/cloudflarehackers/tg-webapp-proxy/blob/main/src/proxy-hook.js): connection interceptor · Rewrites Telegram WebSocket URLs when proxying is enabled. · `src/proxy-hook.js`
- [Cloudflare Pages proxy](https://github.com/cloudflarehackers/tg-webapp-proxy/blob/main/functions/api/%5B%5Bpath%5D%5D.js): HTTP/WebSocket proxy endpoint · Validates Telegram targets before forwarding traffic. · `functions/api/[[path]].js`

## Connections

- SPA entry page → Mode router & bot UI: loads
- Vite build boundary → SPA entry page: serves/bundles
- Mode router & bot UI → Compatibility bootstrap: initializes
- Mode router & bot UI → Bot Telegram client: delegates bot operations
- Mode router & bot UI → User-mode UI: routes user mode
- Mode router & bot UI → Settings: reads/writes
- Mode router & bot UI → Bot history database: restores bot state
- User-mode UI → User Telegram client: invokes account operations
- User-mode UI → Settings: reads/writes
- Bot Telegram client → Telegram link parser: parses retrieval links
- Bot Telegram client → teleproto / MTProto: uses
- User Telegram client → teleproto / MTProto: uses
- teleproto / MTProto → Browser session shim: persists state through
- Browser session shim → Browser localStorage: stores
- teleproto / MTProto → WebSocket transport shim: connects through
- teleproto / MTProto → Crypto & compression shims: uses protocol support
- WebSocket transport shim → Proxy WebSocket hook: WebSocket construction
- Proxy WebSocket hook → Telegram DCs: direct connection
- Proxy WebSocket hook → Cloudflare Pages proxy: when proxy enabled
- Cloudflare Pages proxy → Telegram DCs: forwards validated traffic
- Settings → Browser localStorage: persists preferences
- Vite build boundary → Compatibility bootstrap: aliases/bundles
- Vite build boundary → WebSocket transport shim: aliases/bundles