# nicegram/tdlib-ios architecture

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

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

## Overview

##### Main Components

a. Core Components:
- TDJsonClient: Interface layer to tdlib's C++ API
- Coordinator: Main orchestrator handling requests and responses
- Stream: Custom implementation for data streaming
- Event System: Handles various events and updates

b. Generated Components:
- API Models (Generated from td_api.tl)
- Function Definitions
- Type Definitions

##### Architecture Layers

**[iOS Application Layer]**
- ↕️
**[TDLib-iOS Wrapper Layer]**
- Coordinator
- Stream System
- Event Handling
- ↕️
**[JSON Interface Layer]**
- TDJsonClient
- ↕️
**[Native tdlib Layer]**

##### Key Interactions to Highlight

a. Authentication Flow:
**Coordinator → AuthorizationState Stream → Application**
- ↓
**TDJsonClient → tdlib → Telegram Servers**

b. Request/Response Flow:
**Application → Coordinator.send(TDFunction)**
- ↓
**TDJsonClient (JSON conversion)**
- ↓
**tdlib → Telegram Servers**
- ↓
**Response → Promise<Result>**

##### Implementation Details

a. Component Relationships:
- How Coordinator manages TDJsonClient
- Stream subscription system
- Demonstrate Promise-based async operations

b. Data Flow Markers:

##### External Dependencies
- Integration with TDJSON framework
- PromiseKit dependency
- Telegram API connection points

##### Implementation Notes

Annotations for:
- Generated code components
- Async operations
- Stream subscription points
- Error handling paths

##### The separation between native tdlib and Swift interface

- How authentication flows work
- How requests are processed
- How events are streamed
- How the generated code integrates

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "iOS Application Layer"
        App[iOS Application]
    end

    subgraph "TDLib-iOS Wrapper Layer"
        direction TB
        Coordinator["Coordinator"]:::core
        StreamSystem["Stream System"]:::stream
        EventSystem["Event System"]:::stream
        StreamPromise["Stream Promise"]:::stream
        AutoLockStream["Auto Lock Stream"]:::stream
        FloodStream["Flood Stream"]:::stream
        ErrorHandler["Error Handler"]:::core
        FunctionDefs["Function Definitions"]:::core
        TDParams["TDLib Parameters"]:::core
    end

    subgraph "JSON Interface Layer"
        JsonClient["TDJsonClient"]:::json
        JsonHandler["JSON Handler"]:::json
    end

    subgraph "Native tdlib Layer"
        TDLib["TDLib (C++)"]:::external
    end

    subgraph "Generated Components"
        APIModels["API Models"]:::generated
        EnumDefs["Enum Definitions"]:::generated
    end

    %% Connections
    App --> Coordinator
    Coordinator --> StreamSystem
    Coordinator --> EventSystem
    Coordinator --> JsonClient
    StreamSystem --> StreamPromise
    StreamSystem --> AutoLockStream
    StreamSystem --> FloodStream
    JsonClient --> JsonHandler
    JsonHandler --> TDLib
    Coordinator --> ErrorHandler
    Coordinator --> FunctionDefs
    Coordinator --> TDParams
    FunctionDefs --> APIModels
    FunctionDefs --> EnumDefs

    %% Click Events
    click Coordinator "https://github.com/nicegram/TDLib-iOS/blob/master/TDLib/Coordinator.swift"
    click StreamSystem "https://github.com/nicegram/TDLib-iOS/blob/master/TDLib/Stream.swift"
    click EventSystem "https://github.com/nicegram/TDLib-iOS/blob/master/TDLib/Event.swift"
    click StreamPromise "https://github.com/nicegram/TDLib-iOS/blob/master/TDLib/StreamPromise.swift"
    click AutoLockStream "https://github.com/nicegram/TDLib-iOS/blob/master/TDLib/AutoLockStream.swift"
    click FloodStream "https://github.com/nicegram/TDLib-iOS/blob/master/TDLib/FloodStream.swift"
    click ErrorHandler "https://github.com/nicegram/TDLib-iOS/blob/master/TDLib/Error.swift"
    click FunctionDefs "https://github.com/nicegram/TDLib-iOS/blob/master/TDLib/Function.swift"
    click TDParams "https://github.com/nicegram/TDLib-iOS/blob/master/TDLib/TdlibParameters.swift"
    click JsonClient "https://github.com/nicegram/TDLib-iOS/blob/master/TDLib/TDJsonClient.swift"
    click JsonHandler "https://github.com/nicegram/TDLib-iOS/blob/master/TDLib/JSON.swift"
    click APIModels "https://github.com/nicegram/TDLib-iOS/blob/master/TDLib/Generated/TDLib.generated.swift"
    click EnumDefs "https://github.com/nicegram/TDLib-iOS/blob/master/TDLib/Generated/TDEnum.generated.swift"

    %% Styles
    classDef core fill:#2374e1,color:#fff
    classDef stream fill:#48a145,color:#fff
    classDef json fill:#d45500,color:#fff
    classDef external fill:#666,color:#fff
    classDef generated fill:#ff9900,color:#fff

    %% Legend
    subgraph Legend
        CoreComp["Core Component"]:::core
        StreamComp["Stream Component"]:::stream
        JsonComp["JSON Component"]:::json
        ExtComp["External Component"]:::external
        GenComp["Generated Component"]:::generated
    end
```
