# tdlib/td architecture

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

- Interactive diagram: https://gitdiagram.com/tdlib/td
- Repository: https://github.com/tdlib/td

## Overview

##### Main components
- Core Library Modules:
– Telegram core: “td/telegram” (handles main Telegram functionalities like messaging, file management, connection state, encryption, etc.).
– Protocol implementation: “td/mtproto” (handles the MTProto protocol, encryption negotiation, handshake, and secure connections).
– Network layer: “tdnet” (provides low-level networking abstractions, HTTP/HTTPS handling, and TLS handling).
– Actor framework: “tdactor” (implements the asynchronous actor system for concurrent task handling).
– Database module: “tddb” (provides key-value storage and access using SQLite).
– TL (Type Language) processing: “tdtl” (facilitates generating code from TL scheme definitions).
– Utility libraries: “tdutils” (contains a collection of helper functions, data structures, and lower-level abstractions).
- Build & Configuration:
– CMake scripts (the “CMake” folder, “CMakeLists.txt” in several directories) orchestrate configuration, dependency detection (e.g., OpenSSL, zlib) and build targets.
– Additional configuration files such as “TdConfig.cmake” and “.clang-format” for coding standards.
- Bindings/Interface Layers:
– JSON interface: C interface that works with any language (supported through “td_json_client” intended for languages that can invoke C functions).
– Language-specific bindings: “example/java”, “example/csharp”, “example/python”, “example/swift”, “example/uwp”—each demonstrating how to integrate with Java (JNI), .NET (C++/CLI), and other environments.
- Documentation & Code Generation:
– “td/generate” and related files (PHP scripts, TL parsers) generate API documentation and language interface wrappers.
– “Doxyfile” and associated scripts/files build source-code documentation.
- Testing & Benchmarking:
– “benchmark” directory includes performance tests for various modules.
– “test” directory with additional test cases for components.

##### Relationships and interactions
– The core library components (Telegram, MTProto, Network, etc.) interact closely: the Telegram module calls MTProto for handshake and secure transmission, which in turn uses the network layer (tdnet) to establish low-level connections.
– The asynchronous operation is managed by the actor framework (tdactor), which orchestrates event handling, timeouts, and concurrency throughout the system.
– Data storage (tddb) and file management components work together to store messages and local state.
– The TL and code generation modules process API schemas and produce language-specific bindings and documentation, which then interface with the core library.
– External dependencies (OpenSSL, zlib, gperf) feed into the build process managed via CMake.
– The language-specific examples (under “example”) act as user-facing integration points, relying on the dynamic (TD::TdJson) and static (TD::TdStatic) libraries provided by the core.

##### Architectural patterns and design principles
– Layered Architecture: Separate layers for network, protocol handling, business logic (Telegram API), storage, and asynchronous scheduling.
– Modular decomposition: Each directory (e.g., td, tdactor, tddb) represents a self-contained module with specific responsibilities.
– Asynchronous, message-driven design: Utilizing an actor system (tdactor) to decouple tasks and maintain high performance.
– Separation of interface and implementation: Multiple abstract interfaces (e.g., JSON, Java, .NET bindings) sitting on top of the core library to allow for multilanguage support.
– Cross-platform design: Emphasis on CMake-based configuration and use of portable abstractions in “tdutils” ensures compatibility across many operating systems.

##### Incorporate the relevant technologies and frameworks
– C++17 (core language standard), CMake (for build orchestrations), OpenSSL and zlib (for security and compression), SQLite (for database operations).
– Language-specific integration mechanisms: JNI for Java, C++/CLI for .NET, and JSON C interfaces which facilitate using TDLib from different programming languages.
– Supporting libraries like gperf (for build-time optimization) and custom PHP scripts for code/documentation generation.

##### Final Assembly Advice
– Start with a high-level view by segmenting the system into the primary architectural areas (Core, Bindings, Build, Testing).

## Diagram (Mermaid)

```mermaid
graph TD
    %% Core Modules
    subgraph "Core Modules"
        TCore["Telegram Core Module"]:::core
        MTProto["MTProto Engine"]:::core
        Net["Network Layer"]:::core
        Actor["Actor Framework"]:::core
        DB["Database Module"]:::core
        TL["TL Processing Module"]:::core
        Utils["Utility Libraries"]:::core
    end

    %% Build & Documentation
    subgraph "Build & Documentation"
        Build["Build & Configuration"]:::build
        Docs["Documentation & Code Generation"]:::build
    end

    %% Bindings & Examples
    subgraph "Bindings & Examples"
        Bind["Language Bindings & Examples"]:::binding
    end

    %% Relationships among Core Modules
    TCore -->|"calls"| MTProto
    MTProto -->|"uses"| Net
    Actor -->|"manages"| TCore
    TCore -->|"stores"| DB
    TL -->|"generates"| Docs
    Utils -->|"supports"| TCore

    %% Interactions with Build & Documentation
    Build -->|"configures"| TCore
    Build -->|"configures"| Actor
    Docs -->|"documents"| TCore

    %% Interface with Bindings
    TCore -->|"exposes_API_to"| Bind

    %% Styles
    classDef core fill:#f9c,stroke:#333,stroke-width:2px;
    classDef build fill:#ccf,stroke:#333,stroke-width:2px;
    classDef binding fill:#cfc,stroke:#333,stroke-width:2px;

    %% Click Events
    click TCore "https://github.com/tdlib/td/tree/master/td/telegram"
    click MTProto "https://github.com/tdlib/td/tree/master/td/mtproto"
    click Net "https://github.com/tdlib/td/tree/master/tdnet"
    click Actor "https://github.com/tdlib/td/tree/master/tdactor"
    click DB "https://github.com/tdlib/td/tree/master/tddb"
    click TL "https://github.com/tdlib/td/tree/master/tdtl"
    click Utils "https://github.com/tdlib/td/tree/master/tdutils"
    click Build "https://github.com/tdlib/td/tree/master/CMake folder"
    click Docs "https://github.com/tdlib/td/tree/master/td/generate"
    click Bind "https://github.com/tdlib/td/tree/master/example"
```
