# nuclight/teleperl architecture

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

- Interactive diagram: https://gitdiagram.com/nuclight/teleperl
- Repository: https://github.com/nuclight/teleperl

## Overview

#### Purpose and Entry Points
Teleperl is a pure-Perl client library for Telegram’s MTProto protocol and Telegram API, with example interactive, bot, transfer, CLI, and minimal GUI applications. Main runnable entry points include `cli.pl`, `auth.pl`, `bot.pl`, `download.pl`, `upload.pl`, and `tkx.pl`. Authentication creates a session used by applications.

#### Protocol Transport and MTProto Core
`MTProto.pm` is the low-level protocol layer: it owns Telegram transport/session behavior and depends on generated MTProto TL objects. Network integration is asynchronous through AnyEvent and SOCKS support, represented by `AnyEvTkx.pm` and `AnyEventSocks.pm`. This is the boundary between application code and Telegram data centers/proxies.

#### Telegram API Client Layer
`Telegram.pm` builds Telegram API operations above MTProto and generated schema constructors. Application-facing scripts and higher-level state managers should invoke Telegram API objects rather than construct transport messages directly. The selected generated schema layer materially determines compatibility with Telegram servers.

#### TL Schema, Parsing, and Code Generation
Telegram’s type language is parsed and compiled into Perl packages. `tl.yp` defines the Yapp parser; `tl-gen.pl` generates `MTProto.pm`-adjacent protocol types and `Telegram.pm` API types from schemas. Input schemas live in `res/mtproto.tl` and versioned API files such as `res/layer82-tdesktop.tl`. `TL/Object.pm` provides the common TL object representation/runtime. Generated files are a deliberate compatibility boundary: changing layers may require client logic changes.

#### Authentication and Cryptography
Authorization and secret-handling infrastructure is concentrated in `TeleCrypt/Keys.pm` and `TeleCrypt/SRP.pm`, supporting Telegram key exchange and SRP-related flows. `auth.pl` is the operational login entry point, obtaining an SMS/session code and persisting a reusable session. Cryptographic primitives come from OpenSSL Perl bindings and random/bignum dependencies.

#### Client State, Persistence, and Updates
The `Teleperl` namespace contains stateful client support around the raw API: `Teleperl/Storage.pm` persists local state/session-related data, `Teleperl/PeerCache.pm` resolves and caches Telegram peers, and `Teleperl/UpdateManager.pm` receives/processes update streams. These components isolate long-lived local client state and asynchronous server updates from one-shot API calls.

#### CLI Application Framework
`cli.pl` hosts an interactive command application built on `CLI/Framework.pm`. Command dispatch and command implementations are separated under `CLI/Framework/Command.pm` and `CLI/Framework/Command/`, including authentication-facing, inspection, configuration, and console commands. This framework is an application shell over the Teleperl/Telegram layers, not the protocol implementation itself.

#### Optional Interfaces and Utilities
`tkx.pl`/`ClifTg.pm` provide the minimal Tcl/Tk proof-of-work GUI path, while scripts such as `cborlog.pl`, `cborpack.pl`, and `cborsee.pl` support optional CBOR-based logging/inspection workflows. Runtime configuration is expected externally, based on `teleperl.example.conf`, including API credentials, phone number, and optional proxy settings.

Main entry points: [`Telegram.pm`](https://github.com/nuclight/teleperl/blob/master/Telegram.pm) (Telegram API client), [`tl-gen.pl`](https://github.com/nuclight/teleperl/blob/master/tl-gen.pl) (TL generator), [`Teleperl/Storage.pm`](https://github.com/nuclight/teleperl/blob/master/Teleperl/Storage.pm) (Local storage), [`auth.pl`](https://github.com/nuclight/teleperl/blob/master/auth.pl) (Authentication)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_schema["TL schema & generation"]
  node_schemas["TL schemas<br/>schema inputs<br/>[mtproto.tl]"]
  node_tl_parser["TL parser<br/>Yapp grammar<br/>[tl.yp]"]
  node_tl_generator{{"TL generator<br/>code generator<br/>[tl-gen.pl]"}}
  node_tl_runtime["TL object runtime<br/>TL runtime<br/>[Object.pm]"]
end

subgraph group_core["Protocol &amp; API core"]
  node_mtproto["MTProto transport<br/>protocol core<br/>[MTProto.pm]"]
  node_async_proxy["Async &amp; SOCKS integration<br/>network runtime<br/>[AnyEvTkx.pm]"]
  node_telegram_api["Telegram API client<br/>API layer<br/>[Telegram.pm]"]
  node_crypto_keys["Key exchange<br/>crypto support<br/>[Keys.pm]"]
  node_crypto_srp["SRP flows<br/>crypto support<br/>[SRP.pm]"]
end

subgraph group_state["Client state"]
  node_storage[("Local storage<br/>persistence<br/>[Storage.pm]")]
  node_peer_cache["Peer cache<br/>state manager<br/>[PeerCache.pm]"]
  node_updates["Update manager<br/>state manager<br/>[UpdateManager.pm]"]
end

subgraph group_apps["Applications"]
  node_auth["Authentication<br/>login entry point<br/>[auth.pl]"]
  node_cli["Interactive CLI<br/>application entry point<br/>[cli.pl]"]
  node_cli_framework["CLI framework<br/>command shell<br/>[Framework.pm]"]
  node_scripts["Bot &amp; transfer scripts<br/>application entry points<br/>[bot.pl]"]
  node_gui["Minimal Tcl/Tk GUI<br/>optional interface<br/>[tkx.pl]"]
  node_cbor_tools["CBOR tools<br/>inspection utilities<br/>[cborlog.pl]"]
end

node_telegram_dc(("Telegram data centers<br/>external service"))

node_schemas -->|"input"| node_tl_generator
node_tl_parser -->|"parses"| node_tl_generator
node_tl_generator -->|"generates types for"| node_tl_runtime
node_tl_generator -->|"generates protocol types"| node_mtproto
node_tl_generator -->|"generates API types"| node_telegram_api
node_telegram_api -->|"API calls"| node_mtproto
node_mtproto -->|"async transport"| node_async_proxy
node_async_proxy -->|"network / proxy"| node_telegram_dc
node_mtproto -->|"MTProto session"| node_telegram_dc
node_auth -->|"login flow"| node_telegram_api
node_auth -->|"key exchange"| node_crypto_keys
node_auth -->|"SRP"| node_crypto_srp
node_auth -->|"persists session"| node_storage
node_cli -->|"hosts"| node_cli_framework
node_cli_framework -->|"commands invoke"| node_telegram_api
node_cli_framework -->|"uses state"| node_storage
node_scripts -->|"API operations"| node_telegram_api
node_gui -->|"API operations"| node_telegram_api
node_telegram_api -->|"peer resolution"| node_peer_cache
node_telegram_api -->|"update stream"| node_updates
node_peer_cache -->|"persists cache"| node_storage
node_updates -->|"persists state"| node_storage
node_cbor_tools -.->|"logging / inspection"| node_storage

click node_schemas "https://github.com/nuclight/teleperl/blob/master/res/mtproto.tl"
click node_tl_parser "https://github.com/nuclight/teleperl/blob/master/tl.yp"
click node_tl_generator "https://github.com/nuclight/teleperl/blob/master/tl-gen.pl"
click node_tl_runtime "https://github.com/nuclight/teleperl/blob/master/TL/Object.pm"
click node_mtproto "https://github.com/nuclight/teleperl/blob/master/MTProto.pm"
click node_async_proxy "https://github.com/nuclight/teleperl/blob/master/AnyEvTkx.pm"
click node_telegram_api "https://github.com/nuclight/teleperl/blob/master/Telegram.pm"
click node_crypto_keys "https://github.com/nuclight/teleperl/blob/master/TeleCrypt/Keys.pm"
click node_crypto_srp "https://github.com/nuclight/teleperl/blob/master/TeleCrypt/SRP.pm"
click node_storage "https://github.com/nuclight/teleperl/blob/master/Teleperl/Storage.pm"
click node_peer_cache "https://github.com/nuclight/teleperl/blob/master/Teleperl/PeerCache.pm"
click node_updates "https://github.com/nuclight/teleperl/blob/master/Teleperl/UpdateManager.pm"
click node_auth "https://github.com/nuclight/teleperl/blob/master/auth.pl"
click node_cli "https://github.com/nuclight/teleperl/blob/master/cli.pl"
click node_cli_framework "https://github.com/nuclight/teleperl/blob/master/CLI/Framework.pm"
click node_scripts "https://github.com/nuclight/teleperl/blob/master/bot.pl"
click node_gui "https://github.com/nuclight/teleperl/blob/master/tkx.pl"
click node_cbor_tools "https://github.com/nuclight/teleperl/blob/master/cborlog.pl"

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_schemas,node_tl_parser,node_tl_generator,node_tl_runtime toneBlue
class node_mtproto,node_async_proxy,node_telegram_api,node_crypto_keys,node_crypto_srp toneAmber
class node_storage,node_peer_cache,node_updates toneMint
class node_auth,node_cli,node_cli_framework,node_scripts,node_gui,node_cbor_tools toneRose
class node_telegram_dc toneNeutral
```

## Components

### TL schema & generation

Schema compilation defines Telegram protocol compatibility.

- [TL schemas](https://github.com/nuclight/teleperl/blob/master/res/mtproto.tl): schema inputs · MTProto and versioned Telegram API layer definitions. · `res/mtproto.tl`
- [TL parser](https://github.com/nuclight/teleperl/blob/master/tl.yp): Yapp grammar · `tl.yp`
- [TL generator](https://github.com/nuclight/teleperl/blob/master/tl-gen.pl): code generator · `tl-gen.pl`
- [TL object runtime](https://github.com/nuclight/teleperl/blob/master/TL/Object.pm): TL runtime · `TL/Object.pm`

### Protocol & API core

- [MTProto transport](https://github.com/nuclight/teleperl/blob/master/MTProto.pm): protocol core · Owns Telegram transport and session behavior. · `MTProto.pm`
- [Async & SOCKS integration](https://github.com/nuclight/teleperl/blob/master/AnyEvTkx.pm): network runtime · `AnyEvTkx.pm`
- [Telegram API client](https://github.com/nuclight/teleperl/blob/master/Telegram.pm): API layer · Application-facing Telegram operations built above MTProto. · `Telegram.pm`
- [Key exchange](https://github.com/nuclight/teleperl/blob/master/TeleCrypt/Keys.pm): crypto support · `TeleCrypt/Keys.pm`
- [SRP flows](https://github.com/nuclight/teleperl/blob/master/TeleCrypt/SRP.pm): crypto support · `TeleCrypt/SRP.pm`

### Client state

- [Local storage](https://github.com/nuclight/teleperl/blob/master/Teleperl/Storage.pm): persistence · Persists session-related local state. · `Teleperl/Storage.pm`
- [Peer cache](https://github.com/nuclight/teleperl/blob/master/Teleperl/PeerCache.pm): state manager · Resolves and caches Telegram peers. · `Teleperl/PeerCache.pm`
- [Update manager](https://github.com/nuclight/teleperl/blob/master/Teleperl/UpdateManager.pm): state manager · Processes asynchronous server update streams. · `Teleperl/UpdateManager.pm`

### Applications

- [Authentication](https://github.com/nuclight/teleperl/blob/master/auth.pl): login entry point · Obtains login codes and persists a reusable session. · `auth.pl`
- [Interactive CLI](https://github.com/nuclight/teleperl/blob/master/cli.pl): application entry point · `cli.pl`
- [CLI framework](https://github.com/nuclight/teleperl/blob/master/CLI/Framework.pm): command shell · Dispatches interactive commands and implementations. · `CLI/Framework.pm`
- [Bot & transfer scripts](https://github.com/nuclight/teleperl/blob/master/bot.pl): application entry points · `bot.pl`
- [Minimal Tcl/Tk GUI](https://github.com/nuclight/teleperl/blob/master/tkx.pl): optional interface · `tkx.pl`
- [CBOR tools](https://github.com/nuclight/teleperl/blob/master/cborlog.pl): inspection utilities · `cborlog.pl`

### Other components

- **Telegram data centers**: external service

## Connections

- TL schemas → TL generator: input
- TL parser → TL generator: parses
- TL generator → TL object runtime: generates types for
- TL generator → MTProto transport: generates protocol types
- TL generator → Telegram API client: generates API types
- Telegram API client → MTProto transport: API calls
- MTProto transport → Async & SOCKS integration: async transport
- Async & SOCKS integration → Telegram data centers: network / proxy
- MTProto transport → Telegram data centers: MTProto session
- Authentication → Telegram API client: login flow
- Authentication → Key exchange: key exchange
- Authentication → SRP flows: SRP
- Authentication → Local storage: persists session
- Interactive CLI → CLI framework: hosts
- CLI framework → Telegram API client: commands invoke
- CLI framework → Local storage: uses state
- Bot & transfer scripts → Telegram API client: API operations
- Minimal Tcl/Tk GUI → Telegram API client: API operations
- Telegram API client → Peer cache: peer resolution
- Telegram API client → Update manager: update stream
- Peer cache → Local storage: persists cache
- Update manager → Local storage: persists state
- CBOR tools → Local storage: logging / inspection