# leomehlig/tdlib-ios architecture

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

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

## Overview

##### Project type and purpose
- This is not a client app but a reusable Swift library—TDLib-iOS—that wraps Telegram’s native tdlib C++ library and exposes a strongly typed, promise- and stream-based Swift API. It’s designed for Carthage integration and provides code-generation hooks to stay in sync with tdlib’s JSON API.

##### File structure
- Top-level:
- TDLib.xcodeproj: the Swift framework project
- TDLib/: Swift source: Coordinator, TDJsonClient, Stream, generated API
- TLParser/ + Templates/: Ruby script & stencil templates for Swift code generation
- docs/: Jazzy-generated API documentation
- Cartfile, Gemfile, Travis, SwiftLint, Fastlane: build/test/deploy
- TDLibTests/: unit tests
- Notice the code-generation (TLParser → Templates → TDLib/Generated), the core “Coordinator” facade, the “Stream” observer, and the “TDJsonClient” C++ bridge.

##### Insights from README
- Coordinator wraps TDJsonClient (C++ → JSON), hides handshake/auth/parameter negotiation, exposes authorizeState streams, send(function) → Promise<Result>.
- Promises (PromiseKit) for single calls, Streams for state updates and downloads.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Application
    ClientApp["Client App"]:::orange

    %% Swift Library Internals
    subgraph "TDLib-iOS Swift API"
        direction TB
        Coordinator["Coordinator (Facade)"]:::blue
        streamGroup(("Streams")):::blue
        PromiseIntegration["PromiseKit Integration"]:::blue
        JSONUtils["JSON Utilities"]:::blue
        CoreHelpers(("Core Types & Helpers")):::blue
        subgraph "Generated API Types"
            direction TB
            GeneratedAPI["TDLib/Generated"]:::blue
        end
    end

    %% Native Bridge and tdlib
    subgraph "Native Bridge & tdlib"
        direction TB
        TDJsonClient["TDJsonClient (ObjC++ wrapper)"]:::gray
        TdlibCPP["tdlib C++ library"]:::gray
    end

    %% Code-Generation Pipeline
    subgraph "Code-Generation Pipeline"
        direction TB
        TLParser["TLParser/parser.rb"]:::green
        Templates(("Templates/*.stencil")):::green
    end

    %% Testing, Docs, Build
    subgraph "Support & CI"
        direction TB
        Tests["TDLibTests"]:::gray
        Docs["API Documentation (docs/)"]:::gray
        BuildConfig(("Build/Test/Deploy Config")):::gray
        Project["Swift Framework Project (TDLib.xcodeproj)"]:::gray
    end

    %% Relationships
    ClientApp -->|"send(Function)"| Coordinator
    Coordinator -->|"wraps JSON"| TDJsonClient
    TDJsonClient -->|"calls C++"| TdlibCPP
    TdlibCPP -->|"JSON callback"| TDJsonClient
    TDJsonClient -->|"callback JSON"| Coordinator
    Coordinator -->|"fulfill Promise / emit Stream"| streamGroup
    ClientApp -.->|"subscribe"| streamGroup

    %% Code-gen flow
    TLParser -->|"uses templates"| Templates
    Templates -->|"generate types"| GeneratedAPI
    GeneratedAPI -->|"used by"| Coordinator

    %% Support flows
    Tests -->|"validate code"| Coordinator
    Tests -->|"validate generated API"| GeneratedAPI
    Docs -->|"generated from"| GeneratedAPI
    BuildConfig -->|"builds"| Project

    %% Click Events
    click Coordinator "https://github.com/leomehlig/tdlib-ios/blob/master/TDLib/Coordinator.swift"
    click TDJsonClient "https://github.com/leomehlig/tdlib-ios/blob/master/TDLib/TDJsonClient.swift"
    click JSONUtils "https://github.com/leomehlig/tdlib-ios/blob/master/TDLib/JSON.swift"
    click GeneratedAPI "https://github.com/leomehlig/tdlib-ios/tree/master/TDLib/Generated/"
    click TLParser "https://github.com/leomehlig/tdlib-ios/blob/master/TLParser/parser.rb"
    click Templates "https://github.com/leomehlig/tdlib-ios/blob/master/Templates/EquatableEnum.stencil"
    click Tests "https://github.com/leomehlig/tdlib-ios/blob/master/TDLibTests/TDLibTests.swift"
    click Project "https://github.com/leomehlig/tdlib-ios/blob/master/TDLib.xcodeproj"
    click Docs "https://github.com/leomehlig/tdlib-ios/tree/master/docs/"

    %% Styles
    classDef orange fill:#F6B26B,stroke:#333,stroke-width:1px
    classDef blue fill:#6FA8DC,stroke:#333,stroke-width:1px
    classDef gray fill:#999999,stroke:#333,stroke-width:1px
    classDef green fill:#93C47D,stroke:#333,stroke-width:1px
```
