Introducing a new way to review your PRs.

Read the announcement

ayugram / ayugramdesktop

Desktop Telegram client with good customization and Ghost mode.

View on GitHub

13 documents · Updated Nov 16, 2026

overview

Knowledge Base updated: 2026-11-16

Knowledge Base Index

1. Orientation

This repository is AyuGram Desktop, a Telegram Desktop-derived C++/Qt client. The highest-level flow is application startup creating the app/account/session domain, which connects MTProto networking, API controllers, data caches, storage, and the window/UI shell.

Main parts:

  • Build and codegen: CMake, Telegram target setup, generated sources, and developer tooling.
  • Application lifecycle: entrypoint, global application ownership, crash/update/logging, and platform integration.
  • AyuGram extensions: Ayu-specific settings, state, workers, URL handlers, and custom feature/UI code.
  • Session/API/data stack: account/session orchestration, high-level Telegram API controllers, MTProto transport, in-memory domain models, and persistence/media transfer.
  • Product UI: history/message views, window shell/navigation/notifications, reusable UI toolkit, media/calls/webview/editor surfaces.

Critical state lives in:

  • Main/account/session objects under Telegram/SourceFiles/main/**.
  • In-memory domain caches under Telegram/SourceFiles/data/**.
  • Local persisted account/media state under Telegram/SourceFiles/storage/**.
  • Network/auth/datacenter state in Telegram/SourceFiles/mtproto/**.
  • AyuGram-specific settings/state under Telegram/SourceFiles/ayu/**.

2. Architecture diagrams

flowchart TD
  subgraph Build[Build and generated inputs]
    CMake[CMakeLists.txt]
    Codegen[Telegram/codegen]
    Tools[tools]
  end

  subgraph App[Application runtime]
    Bootstrap[main.cpp and core/application]
    Main[main account/session]
    Ayu[AyuGram ayu subsystem]
  end

  subgraph Backend[Telegram client backend]
    API[api and apiwrap]
    MTProto[mtproto networking]
    Data[data cache/model]
    Storage[storage and transfers]
  end

  subgraph UI[User-facing UI]
    Window[window shell]
    History[history/message view]
    UIToolkit[ui/boxes/layout/menu]
    Media[media/calls/webviews/editor]
  end

  CMake --> Bootstrap
  Codegen --> API
  Bootstrap --> Main
  Bootstrap --> Window
  Main --> API
  Main --> Data
  API --> MTProto
  API --> Data
  Data --> Storage
  Storage --> MTProto
  Window --> History
  History --> Data
  Window --> UIToolkit
  History --> UIToolkit
  Media --> UIToolkit
  Ayu --> Main
  Ayu --> UI
sequenceDiagram
  participant Entry as main.cpp
  participant App as core/application
  participant Main as main/session domain
  participant Net as mtproto
  participant API as api/apiwrap
  participant Data as data cache
  participant UI as window/history UI

  Entry->>App: create and initialize application
  App->>Main: open domain/account/session
  Main->>Net: configure transport and auth state
  Main->>API: construct request controllers
  API->>Data: populate and mutate domain objects
  Main->>UI: attach session controllers
  UI->>Data: render peers, histories, messages
flowchart LR
  UserAction[UI user action] --> History[history/window UI]
  History --> API[api controllers]
  API --> MTProto[MTProto sender/session]
  MTProto --> Telegram[Telegram network]
  Telegram --> MTProto
  MTProto --> API
  API --> Data[data models]
  Data --> Storage[local storage/cache]
  Data --> History
flowchart TD
  FileRequest[media/file request] --> API[api/media or storage caller]
  API --> Transfer[storage transfer pipeline]
  Transfer --> MTProto[MTProto file transport]
  Transfer --> Web[web download path]
  Transfer --> Local[local persistence]
  Local --> Media[media playback/editor/view]
  Media --> UI[window/history UI]

3. Glossary

  • AyuGram: this fork's custom feature layer under Telegram/SourceFiles/ayu/**.
  • MTProto: Telegram's client protocol implementation rooted in Telegram/SourceFiles/mtproto/**.
  • TL: Telegram schema/generated type layer used by API/MTProto code generation.
  • History: Telegram Desktop's chat/message timeline model and view code under Telegram/SourceFiles/history/**.
  • Session: per-account runtime domain tying API, data, storage, network, and UI controllers together under Telegram/SourceFiles/main/**.

4. Codebase-wide invariants

  • The main product source tree is rooted at Telegram/SourceFiles/**; major runtime subsystems are directory-partitioned there, for example api/**, data/**, history/**, main/**, mtproto/**, storage/**, ui/**, and window/**.
  • Build ownership is CMake-centered: repository and app target configuration enter through CMakeLists.txt, Telegram/CMakeLists.txt, and supporting files under Telegram/cmake/**.
  • Most C++ feature units use paired implementation/header files, visible across representative subsystem paths such as Telegram/…/api_sending.cpp + .h, Telegram/…/data_session.cpp + .h, and Telegram/…/window_session_controller.cpp + .h; exceptions include styles, generated/config headers, resources, and platform-specific files.
  • AyuGram-specific product code is isolated under Telegram/SourceFiles/ayu/**, while upstream Telegram Desktop subsystems remain under sibling directories such as api/**, data/**, history/**, and window/**.

5. Routing table