# flowseal/tg-ws-proxy architecture

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

- Interactive diagram: https://gitdiagram.com/flowseal/tg-ws-proxy
- Repository: https://github.com/flowseal/tg-ws-proxy

## Overview

TG WS Proxy is a local MTProto proxy for Telegram Desktop: it accepts Telegram’s local proxy connection, identifies the destination DC, and relays encrypted traffic over WebSocket, with Cloudflare and direct-TCP fallback options. The tray application configures and manages that runtime and offers diagnostics and update checks. The main routing and fallback paths are evidenced by the README and proxy entry-point references; unsampled modules are included where their roles are documented or named, but their internal call links are omitted when not shown.

Main entry points: [`proxy/tg_ws_proxy.py`](https://github.com/flowseal/tg-ws-proxy/blob/main/proxy/tg_ws_proxy.py) (MTProto listener), [`utils/tray_common.py`](https://github.com/flowseal/tg-ws-proxy/blob/main/utils/tray_common.py) (Tray controls), [`ui/settings_form.py`](https://github.com/flowseal/tg-ws-proxy/blob/main/ui/settings_form.py) (Settings editor), [`proxy/cf_h2.py`](https://github.com/flowseal/tg-ws-proxy/blob/main/proxy/cf_h2.py) (Cloudflare HTTP/2)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Tray application"]
  node_tray["Tray controls<br/>[tray_common.py]"]
  node_platform_ui["Platform launchers<br/>[windows.py]"]
  node_settings["Settings editor<br/>[settings_form.py]"]
  node_settings_dialog["Settings dialog<br/>[settings_dialog.py]"]
  node_tray_widgets["Tray widgets<br/>[ctk_tray_ui.py]"]
  node_ui_theme["Theme and controls<br/>[ctk_theme.py]"]
end

subgraph group_runtime["Proxy runtime"]
  node_local_proxy["MTProto listener<br/>[tg_ws_proxy.py]"]
  node_bridge["Traffic bridge<br/>[bridge.py]"]
  node_obfuscation["AES obfuscation<br/>[_aes.py]"]
  node_fake_tls["Fake TLS<br/>[fake_tls.py]"]
end

subgraph group_routing["Transport routing"]
  node_ws_route["Telegram WebSocket<br/>[raw_websocket.py]"]
  node_fallback["Fallback routing<br/>[tg_ws_proxy.py]"]
  node_cf_h2["Cloudflare HTTP/2<br/>[cf_h2.py]"]
  node_transport["HTTP/2 transport<br/>[h2_transport.py]"]
  node_ws_pool["WebSocket pool<br/>[pool.py]"]
  node_balancer["Domain balancer<br/>[balancer.py]"]
end

subgraph group_support["Configuration and status"]
  node_config["Proxy configuration<br/>[config.py]"]
  node_network_debug["Network diagnostics<br/>[network_debug.py]"]
  node_stats["Traffic statistics<br/>[stats.py]"]
  node_settings_store["Tray config and logs<br/>[tray_common.py]"]
  node_update_check["Update checker<br/>[update_check.py]"]
  node_locales["Translations<br/>[__init__.py]"]
end

node_telegram(("Telegram Desktop"))
node_telegram_dc(("Telegram DC"))
node_cloudflare(("Cloudflare proxy"))
node_direct_tcp(("Direct TCP"))

node_telegram -->|"connects locally"| node_local_proxy
node_local_proxy -->|"dispatches relay"| node_bridge
node_local_proxy -->|"opens WebSocket"| node_ws_route
node_local_proxy -->|"routes when unavailable"| node_fallback
node_fallback -->|"uses H2 pool"| node_cf_h2
node_fallback -->|"falls back to TCP"| node_direct_tcp
node_ws_route -->|"relays encrypted traffic"| node_telegram_dc
node_cf_h2 -->|"uses transport"| node_transport
node_cf_h2 -->|"sends H2 requests"| node_cloudflare
node_local_proxy -->|"reuses connections"| node_ws_pool
node_ws_pool -->|"pools WebSockets"| node_ws_route
node_config -->|"updates domains"| node_balancer
node_tray -->|"starts and restarts"| node_local_proxy
node_tray -->|"loads and saves"| node_settings_store
node_tray -->|"opens settings"| node_settings_dialog
node_settings_dialog -->|"builds form"| node_settings
node_settings -->|"uses widgets"| node_tray_widgets
node_settings -->|"offers update check"| node_update_check
node_tray -->|"checks releases"| node_update_check
node_tray -->|"applies settings"| node_config
node_local_proxy -->|"reads routing config"| node_config
node_bridge -->|"records traffic"| node_stats
node_local_proxy -->|"dispatches TLS mode"| node_fake_tls
node_settings -->|"translates labels"| node_locales
node_platform_ui -->|"uses common tray"| node_tray
node_tray_widgets -->|"uses styling"| node_ui_theme

click node_tray "https://github.com/flowseal/tg-ws-proxy/blob/main/utils/tray_common.py"
click node_platform_ui "https://github.com/flowseal/tg-ws-proxy/blob/main/windows.py"
click node_settings "https://github.com/flowseal/tg-ws-proxy/blob/main/ui/settings_form.py"
click node_settings_dialog "https://github.com/flowseal/tg-ws-proxy/blob/main/ui/settings_dialog.py"
click node_tray_widgets "https://github.com/flowseal/tg-ws-proxy/blob/main/ui/ctk_tray_ui.py"
click node_ui_theme "https://github.com/flowseal/tg-ws-proxy/blob/main/ui/ctk_theme.py"
click node_local_proxy "https://github.com/flowseal/tg-ws-proxy/blob/main/proxy/tg_ws_proxy.py"
click node_bridge "https://github.com/flowseal/tg-ws-proxy/blob/main/proxy/bridge.py"
click node_obfuscation "https://github.com/flowseal/tg-ws-proxy/blob/main/proxy/_aes.py"
click node_fake_tls "https://github.com/flowseal/tg-ws-proxy/blob/main/proxy/fake_tls.py"
click node_ws_route "https://github.com/flowseal/tg-ws-proxy/blob/main/proxy/raw_websocket.py"
click node_fallback "https://github.com/flowseal/tg-ws-proxy/blob/main/proxy/tg_ws_proxy.py"
click node_cf_h2 "https://github.com/flowseal/tg-ws-proxy/blob/main/proxy/cf_h2.py"
click node_transport "https://github.com/flowseal/tg-ws-proxy/blob/main/proxy/h2_transport.py"
click node_ws_pool "https://github.com/flowseal/tg-ws-proxy/blob/main/proxy/pool.py"
click node_balancer "https://github.com/flowseal/tg-ws-proxy/blob/main/proxy/balancer.py"
click node_config "https://github.com/flowseal/tg-ws-proxy/blob/main/proxy/config.py"
click node_network_debug "https://github.com/flowseal/tg-ws-proxy/blob/main/proxy/network_debug.py"
click node_stats "https://github.com/flowseal/tg-ws-proxy/blob/main/proxy/stats.py"
click node_settings_store "https://github.com/flowseal/tg-ws-proxy/blob/main/utils/tray_common.py"
click node_update_check "https://github.com/flowseal/tg-ws-proxy/blob/main/utils/update_check.py"
click node_locales "https://github.com/flowseal/tg-ws-proxy/blob/main/ui/i18n/__init__.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_tray,node_platform_ui,node_settings,node_settings_dialog,node_tray_widgets,node_ui_theme toneBlue
class node_local_proxy,node_bridge,node_obfuscation,node_fake_tls toneAmber
class node_ws_route,node_fallback,node_cf_h2,node_transport,node_ws_pool,node_balancer toneMint
class node_config,node_network_debug,node_stats,node_settings_store,node_update_check,node_locales toneRose
class node_telegram,node_telegram_dc,node_cloudflare,node_direct_tcp toneIndigo
```

## Components

### Tray application

- [Tray controls](https://github.com/flowseal/tg-ws-proxy/blob/main/utils/tray_common.py): `utils/tray_common.py`
- [Platform launchers](https://github.com/flowseal/tg-ws-proxy/blob/main/windows.py): `windows.py`
- [Settings editor](https://github.com/flowseal/tg-ws-proxy/blob/main/ui/settings_form.py): `ui/settings_form.py`
- [Settings dialog](https://github.com/flowseal/tg-ws-proxy/blob/main/ui/settings_dialog.py): `ui/settings_dialog.py`
- [Tray widgets](https://github.com/flowseal/tg-ws-proxy/blob/main/ui/ctk_tray_ui.py): `ui/ctk_tray_ui.py`
- [Theme and controls](https://github.com/flowseal/tg-ws-proxy/blob/main/ui/ctk_theme.py): `ui/ctk_theme.py`

### Proxy runtime

- [MTProto listener](https://github.com/flowseal/tg-ws-proxy/blob/main/proxy/tg_ws_proxy.py): `proxy/tg_ws_proxy.py`
- [Traffic bridge](https://github.com/flowseal/tg-ws-proxy/blob/main/proxy/bridge.py): `proxy/bridge.py`
- [AES obfuscation](https://github.com/flowseal/tg-ws-proxy/blob/main/proxy/_aes.py): `proxy/_aes.py`
- [Fake TLS](https://github.com/flowseal/tg-ws-proxy/blob/main/proxy/fake_tls.py): `proxy/fake_tls.py`

### Transport routing

- [Telegram WebSocket](https://github.com/flowseal/tg-ws-proxy/blob/main/proxy/raw_websocket.py): `proxy/raw_websocket.py`
- [Fallback routing](https://github.com/flowseal/tg-ws-proxy/blob/main/proxy/tg_ws_proxy.py): `proxy/tg_ws_proxy.py`
- [Cloudflare HTTP/2](https://github.com/flowseal/tg-ws-proxy/blob/main/proxy/cf_h2.py): `proxy/cf_h2.py`
- [HTTP/2 transport](https://github.com/flowseal/tg-ws-proxy/blob/main/proxy/h2_transport.py): `proxy/h2_transport.py`
- [WebSocket pool](https://github.com/flowseal/tg-ws-proxy/blob/main/proxy/pool.py): `proxy/pool.py`
- [Domain balancer](https://github.com/flowseal/tg-ws-proxy/blob/main/proxy/balancer.py): `proxy/balancer.py`

### Configuration and status

- [Proxy configuration](https://github.com/flowseal/tg-ws-proxy/blob/main/proxy/config.py): `proxy/config.py`
- [Network diagnostics](https://github.com/flowseal/tg-ws-proxy/blob/main/proxy/network_debug.py): `proxy/network_debug.py`
- [Traffic statistics](https://github.com/flowseal/tg-ws-proxy/blob/main/proxy/stats.py): `proxy/stats.py`
- [Tray config and logs](https://github.com/flowseal/tg-ws-proxy/blob/main/utils/tray_common.py): `utils/tray_common.py`
- [Update checker](https://github.com/flowseal/tg-ws-proxy/blob/main/utils/update_check.py): `utils/update_check.py`
- [Translations](https://github.com/flowseal/tg-ws-proxy/blob/main/ui/i18n/__init__.py): `ui/i18n/__init__.py`

### Other components

- **Telegram Desktop**
- **Telegram DC**
- **Cloudflare proxy**
- **Direct TCP**

## Connections

- Telegram Desktop → MTProto listener: connects locally
- MTProto listener → Traffic bridge: dispatches relay (evidence: `proxy/tg_ws_proxy.py`)
- MTProto listener → Telegram WebSocket: opens WebSocket (evidence: `proxy/tg_ws_proxy.py`)
- MTProto listener → Fallback routing: routes when unavailable (evidence: `proxy/tg_ws_proxy.py`)
- Fallback routing → Cloudflare HTTP/2: uses H2 pool (evidence: `proxy/tg_ws_proxy.py`)
- Fallback routing → Direct TCP: falls back to TCP
- Telegram WebSocket → Telegram DC: relays encrypted traffic
- Cloudflare HTTP/2 → HTTP/2 transport: uses transport (evidence: `proxy/cf_h2.py`)
- Cloudflare HTTP/2 → Cloudflare proxy: sends H2 requests
- MTProto listener → WebSocket pool: reuses connections (evidence: `proxy/tg_ws_proxy.py`)
- WebSocket pool → Telegram WebSocket: pools WebSockets (evidence: `proxy/pool.py`)
- Proxy configuration → Domain balancer: updates domains (evidence: `proxy/config.py`)
- Tray controls → MTProto listener: starts and restarts (evidence: `utils/tray_common.py`)
- Tray controls → Tray config and logs: loads and saves (evidence: `utils/tray_common.py`)
- Tray controls → Settings dialog: opens settings (evidence: `utils/tray_common.py`)
- Settings dialog → Settings editor: builds form (evidence: `ui/settings_dialog.py`)
- Settings editor → Tray widgets: uses widgets (evidence: `ui/ctk_tray_ui.py`)
- Settings editor → Update checker: offers update check (evidence: `ui/settings_form.py`)
- Tray controls → Update checker: checks releases (evidence: `utils/tray_common.py`)
- Tray controls → Proxy configuration: applies settings (evidence: `utils/tray_common.py`)
- MTProto listener → Proxy configuration: reads routing config (evidence: `proxy/tg_ws_proxy.py`)
- Traffic bridge → Traffic statistics: records traffic (evidence: `proxy/bridge.py`)
- MTProto listener → Fake TLS: dispatches TLS mode (evidence: `proxy/tg_ws_proxy.py`)
- Settings editor → Translations: translates labels (evidence: `ui/settings_form.py`)
- Platform launchers → Tray controls: uses common tray (evidence: `windows.py`)
- Tray widgets → Theme and controls: uses styling (evidence: `ui/ctk_tray_ui.py`)
