# telemt/telemt architecture

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

- Interactive diagram: https://gitdiagram.com/telemt/telemt
- Repository: https://github.com/telemt/telemt

## Overview

Telemt is a Rust/Tokio Telegram MTProto proxy. The primary workflow accepts client connections, negotiates an MTProto proxy mode, and relays traffic directly or through configured middle-end proxies. It also supports TLS fronting, optional web traffic masking, runtime configuration and user administration, and operational metrics. The graph combines README-documented capabilities with sampled entry-point and configuration/API code; most proxy and web internals are represented at subsystem level because their implementation was not sampled.

Main entry points: [`src/maestro/orchestrator.rs`](https://github.com/telemt/telemt/blob/main/src/maestro/orchestrator.rs) (Runtime orchestration), [`src/maestro/listeners.rs`](https://github.com/telemt/telemt/blob/main/src/maestro/listeners.rs) (Proxy listeners), [`src/proxy/handshake.rs`](https://github.com/telemt/telemt/blob/main/src/proxy/handshake.rs) (Client handshake), [`src/proxy/relay.rs`](https://github.com/telemt/telemt/blob/main/src/proxy/relay.rs) (Traffic relay)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime and config"]
  node_main["Process entry<br/>[main.rs]"]
  node_maestro["Runtime orchestration<br/>[orchestrator.rs]"]
  node_config_load["Config loading<br/>[pipeline.rs]"]
  node_reload["Hot reload<br/>[hot_reload.rs]"]
end

subgraph group_proxy["MTProto proxy"]
  node_listener["Proxy listeners<br/>[listeners.rs]"]
  node_handshake["Client handshake<br/>[handshake.rs]"]
  node_protocol["MTProto framing<br/>[mod.rs]"]
  node_relay["Traffic relay<br/>[relay.rs]"]
end

subgraph group_upstream["Upstream transport"]
  node_upstream_mgr["Upstream selection<br/>[upstream.rs]"]
  node_middle_pool["Middle-end pool<br/>[pool.rs]"]
end

subgraph group_web["Web and fronting"]
  node_masking["Traffic masking<br/>[masking.rs]"]
  node_tls_front["TLS fronting<br/>[mod.rs]"]
  node_web_runtime["Web runtime<br/>[manager.rs]"]
  node_trace_store[("Web trace store<br/>[store.rs]")]
end

subgraph group_ops["Operations"]
  node_api["Control API<br/>[mod.rs]"]
  node_user_routes["User operations<br/>[user_routes.rs]"]
  node_stats["Statistics<br/>[mod.rs]"]
  node_metrics["Metrics endpoint<br/>[web.rs]"]
end

node_operator(("Operator"))
node_client(("Telegram client"))
node_telegram(("Telegram network"))
node_decoy(("Decoy web server"))
node_config_file["Config files"]

node_operator -->|"starts process"| node_main
node_main -->|"runs server"| node_maestro
node_maestro -->|"loads config"| node_config_load
node_config_file -->|"reads settings"| node_config_load
node_maestro -->|"starts listeners"| node_listener
node_operator -->|"manages proxy"| node_api
node_api -->|"dispatches user routes"| node_user_routes
node_user_routes -->|"reads and updates"| node_config_file
node_operator -->|"provides settings"| node_config_file
node_client -->|"connects"| node_listener
node_listener -->|"accepts connection"| node_handshake
node_handshake -->|"negotiates framing"| node_protocol
node_handshake -.->|"handles fake TLS"| node_tls_front
node_protocol -->|"passes framed traffic"| node_relay
node_relay -->|"requests route"| node_upstream_mgr
node_upstream_mgr -->|"connects directly"| node_telegram
node_upstream_mgr -->|"selects pooled route"| node_middle_pool
node_middle_pool -->|"forwards traffic"| node_telegram
node_listener -.->|"forwards unrecognized traffic"| node_masking
node_masking -.->|"relays web traffic"| node_decoy
node_maestro -->|"coordinates reload"| node_reload
node_api -->|"submits reload"| node_maestro
node_relay -->|"records activity"| node_stats
node_metrics -->|"renders measurements"| node_stats
node_operator -->|"scrapes metrics"| node_metrics
node_web_runtime -->|"stores traces"| node_trace_store

click node_main "https://github.com/telemt/telemt/blob/main/src/main.rs"
click node_maestro "https://github.com/telemt/telemt/blob/main/src/maestro/orchestrator.rs"
click node_config_load "https://github.com/telemt/telemt/blob/main/src/config/load/pipeline.rs"
click node_reload "https://github.com/telemt/telemt/blob/main/src/config/hot_reload.rs"
click node_api "https://github.com/telemt/telemt/blob/main/src/api/mod.rs"
click node_user_routes "https://github.com/telemt/telemt/blob/main/src/api/handler/user_routes.rs"
click node_listener "https://github.com/telemt/telemt/blob/main/src/maestro/listeners.rs"
click node_handshake "https://github.com/telemt/telemt/blob/main/src/proxy/handshake.rs"
click node_protocol "https://github.com/telemt/telemt/blob/main/src/protocol/mod.rs"
click node_relay "https://github.com/telemt/telemt/blob/main/src/proxy/relay.rs"
click node_masking "https://github.com/telemt/telemt/blob/main/src/proxy/masking.rs"
click node_upstream_mgr "https://github.com/telemt/telemt/blob/main/src/transport/upstream.rs"
click node_middle_pool "https://github.com/telemt/telemt/blob/main/src/transport/middle_proxy/pool.rs"
click node_tls_front "https://github.com/telemt/telemt/blob/main/src/tls_front/mod.rs"
click node_web_runtime "https://github.com/telemt/telemt/blob/main/src/web/manager.rs"
click node_trace_store "https://github.com/telemt/telemt/blob/main/src/web/trace/store.rs"
click node_stats "https://github.com/telemt/telemt/blob/main/src/stats/mod.rs"
click node_metrics "https://github.com/telemt/telemt/blob/main/src/metrics/web.rs"

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,node_maestro,node_config_load,node_reload,node_client toneBlue
class node_listener,node_handshake,node_protocol,node_relay toneAmber
class node_upstream_mgr,node_middle_pool,node_decoy toneMint
class node_masking,node_tls_front,node_web_runtime,node_trace_store toneRose
class node_api,node_user_routes,node_stats,node_metrics,node_operator,node_telegram,node_config_file toneIndigo
```

## Components

### Runtime and config

- [Process entry](https://github.com/telemt/telemt/blob/main/src/main.rs): `src/main.rs`
- [Runtime orchestration](https://github.com/telemt/telemt/blob/main/src/maestro/orchestrator.rs): `src/maestro/orchestrator.rs`
- [Config loading](https://github.com/telemt/telemt/blob/main/src/config/load/pipeline.rs): `src/config/load/pipeline.rs`
- [Hot reload](https://github.com/telemt/telemt/blob/main/src/config/hot_reload.rs): `src/config/hot_reload.rs`

### MTProto proxy

- [Proxy listeners](https://github.com/telemt/telemt/blob/main/src/maestro/listeners.rs): `src/maestro/listeners.rs`
- [Client handshake](https://github.com/telemt/telemt/blob/main/src/proxy/handshake.rs): `src/proxy/handshake.rs`
- [MTProto framing](https://github.com/telemt/telemt/blob/main/src/protocol/mod.rs): `src/protocol/mod.rs`
- [Traffic relay](https://github.com/telemt/telemt/blob/main/src/proxy/relay.rs): `src/proxy/relay.rs`

### Upstream transport

- [Upstream selection](https://github.com/telemt/telemt/blob/main/src/transport/upstream.rs): `src/transport/upstream.rs`
- [Middle-end pool](https://github.com/telemt/telemt/blob/main/src/transport/middle_proxy/pool.rs): `src/transport/middle_proxy/pool.rs`

### Web and fronting

- [Traffic masking](https://github.com/telemt/telemt/blob/main/src/proxy/masking.rs): `src/proxy/masking.rs`
- [TLS fronting](https://github.com/telemt/telemt/blob/main/src/tls_front/mod.rs): `src/tls_front/mod.rs`
- [Web runtime](https://github.com/telemt/telemt/blob/main/src/web/manager.rs): `src/web/manager.rs`
- [Web trace store](https://github.com/telemt/telemt/blob/main/src/web/trace/store.rs): `src/web/trace/store.rs`

### Operations

- [Control API](https://github.com/telemt/telemt/blob/main/src/api/mod.rs): `src/api/mod.rs`
- [User operations](https://github.com/telemt/telemt/blob/main/src/api/handler/user_routes.rs): `src/api/handler/user_routes.rs`
- [Statistics](https://github.com/telemt/telemt/blob/main/src/stats/mod.rs): `src/stats/mod.rs`
- [Metrics endpoint](https://github.com/telemt/telemt/blob/main/src/metrics/web.rs): `src/metrics/web.rs`

### Other components

- **Operator**
- **Telegram client**
- **Telegram network**
- **Decoy web server**
- **Config files**

## Connections

- Operator → Process entry: starts process
- Process entry → Runtime orchestration: runs server
- Runtime orchestration → Config loading: loads config
- Config files → Config loading: reads settings
- Runtime orchestration → Proxy listeners: starts listeners
- Operator → Control API: manages proxy
- Control API → User operations: dispatches user routes
- User operations → Config files: reads and updates
- Operator → Config files: provides settings
- Telegram client → Proxy listeners: connects
- Proxy listeners → Client handshake: accepts connection
- Client handshake → MTProto framing: negotiates framing
- Client handshake → TLS fronting: handles fake TLS
- MTProto framing → Traffic relay: passes framed traffic
- Traffic relay → Upstream selection: requests route
- Upstream selection → Telegram network: connects directly
- Upstream selection → Middle-end pool: selects pooled route
- Middle-end pool → Telegram network: forwards traffic
- Proxy listeners → Traffic masking: forwards unrecognized traffic
- Traffic masking → Decoy web server: relays web traffic
- Runtime orchestration → Hot reload: coordinates reload
- Control API → Runtime orchestration: submits reload
- Traffic relay → Statistics: records activity
- Metrics endpoint → Statistics: renders measurements
- Operator → Metrics endpoint: scrapes metrics
- Web runtime → Web trace store: stores traces