# tud8951/cf-workers-tgproxy architecture

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

- Interactive diagram: https://gitdiagram.com/tud8951/cf-workers-tgproxy
- Repository: https://github.com/tud8951/cf-workers-tgproxy

## Overview

CF-Workers-TGProxy is a single-file Cloudflare Worker that serves Telegram’s web-proxy page and converts client WebSocket lanes into connections to Telegram Web K’s KWS endpoints. The main workflow is page/bootstrap → session token and lease → per-stream lane → transport obfuscation re-signing → KWS relay, with aggregation on the data path. The README documents the major capabilities; the excerpt confirms token signing, in-memory leases, AES-CTR handling, KWS dialing and lane setup. Details of the omitted router and relay internals are therefore attributed to README documentation.

Main entry points: [`telegram_webproxy.js`](https://github.com/tud8951/cf-workers-tgproxy/blob/main/telegram_webproxy.js) (Lane session)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Page and ingress"]
  node_worker["Worker entry"]
  node_proxy_page["Proxy page"]
  node_android_bridge["Android bridge"]
end

subgraph group_security["Auth and session"]
  node_session_api["Session API"]
  node_token_auth["Token signing"]
  node_lease_state["Lease state"]
end

subgraph group_relay["Lane relay"]
  node_lane_api["Lane WebSocket"]
  node_lane_session["Lane session"]
  node_obfuscation["Obfuscation transform"]
  node_kws_dial["KWS dialer"]
  node_aggregation["Frame aggregation"]
  node_relay_io["WebSocket relay I/O"]
end

node_clients(("Telegram clients"))
node_kws(("Telegram Web K"))

node_clients -->|"loads page"| node_proxy_page
node_worker -->|"serves"| node_proxy_page
node_proxy_page -->|"bridges messages"| node_android_bridge
node_proxy_page -->|"requests session"| node_session_api
node_session_api -->|"verifies and signs"| node_token_auth
node_session_api -->|"creates lease"| node_lease_state
node_proxy_page -->|"opens lane"| node_lane_api
node_lane_api -->|"verifies token"| node_token_auth
node_lane_api -->|"checks lease"| node_lease_state
node_lane_api -->|"attaches session"| node_lane_session
node_lane_session -->|"resigns transport"| node_obfuscation
node_lane_session -->|"dials upstream"| node_kws_dial
node_kws_dial -->|"connects WebSocket"| node_kws
node_lane_session -->|"bundles frames"| node_aggregation
node_lane_session -->|"relays bytes"| node_relay_io
node_relay_io -->|"forwards traffic"| node_kws

click node_worker "https://github.com/tud8951/cf-workers-tgproxy/blob/main/telegram_webproxy.js"
click node_proxy_page "https://github.com/tud8951/cf-workers-tgproxy/blob/main/telegram_webproxy.js"
click node_android_bridge "https://github.com/tud8951/cf-workers-tgproxy/blob/main/telegram_webproxy.js"
click node_session_api "https://github.com/tud8951/cf-workers-tgproxy/blob/main/telegram_webproxy.js"
click node_token_auth "https://github.com/tud8951/cf-workers-tgproxy/blob/main/telegram_webproxy.js"
click node_lease_state "https://github.com/tud8951/cf-workers-tgproxy/blob/main/telegram_webproxy.js"
click node_lane_api "https://github.com/tud8951/cf-workers-tgproxy/blob/main/telegram_webproxy.js"
click node_lane_session "https://github.com/tud8951/cf-workers-tgproxy/blob/main/telegram_webproxy.js"
click node_obfuscation "https://github.com/tud8951/cf-workers-tgproxy/blob/main/telegram_webproxy.js"
click node_kws_dial "https://github.com/tud8951/cf-workers-tgproxy/blob/main/telegram_webproxy.js"
click node_aggregation "https://github.com/tud8951/cf-workers-tgproxy/blob/main/telegram_webproxy.js"
click node_relay_io "https://github.com/tud8951/cf-workers-tgproxy/blob/main/telegram_webproxy.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_worker,node_proxy_page,node_android_bridge,node_clients toneBlue
class node_session_api,node_token_auth,node_lease_state toneAmber
class node_lane_api,node_lane_session,node_obfuscation,node_kws_dial,node_aggregation,node_relay_io toneMint
class node_kws toneIndigo
```

## Components

### Page and ingress

- [Worker entry](https://github.com/tud8951/cf-workers-tgproxy/blob/main/telegram_webproxy.js): `telegram_webproxy.js`
- [Proxy page](https://github.com/tud8951/cf-workers-tgproxy/blob/main/telegram_webproxy.js): `telegram_webproxy.js`
- [Android bridge](https://github.com/tud8951/cf-workers-tgproxy/blob/main/telegram_webproxy.js): `telegram_webproxy.js`

### Auth and session

- [Session API](https://github.com/tud8951/cf-workers-tgproxy/blob/main/telegram_webproxy.js): `telegram_webproxy.js`
- [Token signing](https://github.com/tud8951/cf-workers-tgproxy/blob/main/telegram_webproxy.js): `telegram_webproxy.js`
- [Lease state](https://github.com/tud8951/cf-workers-tgproxy/blob/main/telegram_webproxy.js): `telegram_webproxy.js`

### Lane relay

- [Lane WebSocket](https://github.com/tud8951/cf-workers-tgproxy/blob/main/telegram_webproxy.js): `telegram_webproxy.js`
- [Lane session](https://github.com/tud8951/cf-workers-tgproxy/blob/main/telegram_webproxy.js): `telegram_webproxy.js`
- [Obfuscation transform](https://github.com/tud8951/cf-workers-tgproxy/blob/main/telegram_webproxy.js): `telegram_webproxy.js`
- [KWS dialer](https://github.com/tud8951/cf-workers-tgproxy/blob/main/telegram_webproxy.js): `telegram_webproxy.js`
- [Frame aggregation](https://github.com/tud8951/cf-workers-tgproxy/blob/main/telegram_webproxy.js): `telegram_webproxy.js`
- [WebSocket relay I/O](https://github.com/tud8951/cf-workers-tgproxy/blob/main/telegram_webproxy.js): `telegram_webproxy.js`

### Other components

- **Telegram clients**
- **Telegram Web K**

## Connections

- Telegram clients → Proxy page: loads page (evidence: `README.md`)
- Worker entry → Proxy page: serves (evidence: `README.md`)
- Proxy page → Android bridge: bridges messages (evidence: `README.md`)
- Proxy page → Session API: requests session (evidence: `README.md`)
- Session API → Token signing: verifies and signs (evidence: `telegram_webproxy.js`)
- Session API → Lease state: creates lease (evidence: `README.md`)
- Proxy page → Lane WebSocket: opens lane (evidence: `README.md`)
- Lane WebSocket → Token signing: verifies token (evidence: `telegram_webproxy.js`)
- Lane WebSocket → Lease state: checks lease (evidence: `README.md`)
- Lane WebSocket → Lane session: attaches session (evidence: `telegram_webproxy.js`)
- Lane session → Obfuscation transform: resigns transport (evidence: `README.md`)
- Lane session → KWS dialer: dials upstream (evidence: `README.md`)
- KWS dialer → Telegram Web K: connects WebSocket (evidence: `telegram_webproxy.js`)
- Lane session → Frame aggregation: bundles frames (evidence: `README.md`)
- Lane session → WebSocket relay I/O: relays bytes (evidence: `README.md`)
- WebSocket relay I/O → Telegram Web K: forwards traffic (evidence: `README.md`)
