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 exampleapi/**,data/**,history/**,main/**,mtproto/**,storage/**,ui/**, andwindow/**. - 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 asapi/**,data/**,history/**, andwindow/**.
5. Routing table
-
Telegram/cmake/**-> docs/build-system-codegen.md -
Telegram/codegen/**-> docs/build-system-codegen.md -
Telegram/SourceFiles/codegen/**-> docs/build-system-codegen.md -
cmake/**-> docs/build-system-codegen.md -
tools/**-> docs/build-system-codegen.md -
.github/**-> docs/build-system-codegen.md -
any change to build configuration, generated source inputs, CI/tooling, or build documentation -> docs/build-system-codegen.md
-
Telegram/…/main.cpp -> docs/application-bootstrap-lifecycle.md
-
Telegram/…/stdafx.h -> docs/application-bootstrap-lifecycle.md
-
Telegram/SourceFiles/logs.*-> docs/application-bootstrap-lifecycle.md -
Telegram/SourceFiles/core/application.*-> docs/application-bootstrap-lifecycle.md -
Telegram/SourceFiles/core/base_integration.*-> docs/application-bootstrap-lifecycle.md -
Telegram/SourceFiles/core/launcher.*-> docs/application-bootstrap-lifecycle.md -
Telegram/SourceFiles/core/crash_*.*-> docs/application-bootstrap-lifecycle.md -
Telegram/SourceFiles/core/update_*.*-> docs/application-bootstrap-lifecycle.md -
Telegram/SourceFiles/mainwindow.*-> docs/application-bootstrap-lifecycle.md -
Telegram/SourceFiles/mainwidget.*-> docs/application-bootstrap-lifecycle.md -
Telegram/SourceFiles/platform/**-> docs/application-bootstrap-lifecycle.md -
any change to startup, shutdown, crash reporting, update checks, logging, or platform bootstrap -> docs/application-bootstrap-lifecycle.md
-
Telegram/SourceFiles/ayu/**-> docs/ayugram-custom-features.md -
docs/web-proxy-test-plan.md -> docs/ayugram-custom-features.md
-
any AyuGram-specific settings, worker, URL handler, feature, or custom UI behavior -> docs/ayugram-custom-features.md
-
Telegram/SourceFiles/main/**-> docs/main-account-session-domain.md -
Telegram/SourceFiles/core/core_settings.*-> docs/main-account-session-domain.md -
Telegram/SourceFiles/core/core_settings_proxy.*-> docs/main-account-session-domain.md -
Telegram/SourceFiles/core/core_cloud_password.*-> docs/main-account-session-domain.md -
Telegram/…/cached_webview_availability.h -> docs/main-account-session-domain.md
-
any change to account/session/domain lifecycle or app/session settings -> docs/main-account-session-domain.md
-
Telegram/SourceFiles/mtproto/**-> docs/mtproto-networking.md -
Telegram/SourceFiles/core/proxy_rotation_manager.*-> docs/mtproto-networking.md -
any change to datacenter config, auth keys, MTProto senders/sessions, TCP/HTTP transport, proxy checks, or web-proxy transport -> docs/mtproto-networking.md
-
Telegram/SourceFiles/api/**-> docs/api-request-layer.md -
Telegram/SourceFiles/apiwrap.*-> docs/api-request-layer.md -
any new high-level Telegram API controller, request manager, update handler, message send/edit path, search/media/privacy/premium/statistics API behavior -> docs/api-request-layer.md
-
Telegram/SourceFiles/data/**-> docs/data-model-session-cache.md -
any change to in-memory users, peers, chats/channels, histories, messages, media, stories, reactions, filters, notifications data, raw TL adaptation, or data session cache behavior -> docs/data-model-session-cache.md
-
Telegram/SourceFiles/storage/**-> docs/storage-persistence-media-transfer.md -
Telegram/SourceFiles/export/**-> docs/storage-persistence-media-transfer.md -
any change to local persistence, account/domain storage, serialization, file locks, upload/download, streamed downloads, local image loading, or export behavior -> docs/storage-persistence-media-transfer.md
-
Telegram/SourceFiles/history/**-> docs/history-message-view.md -
Telegram/SourceFiles/chat_helpers/**-> docs/history-message-view.md -
Telegram/SourceFiles/dialogs/**-> docs/history-message-view.md -
Telegram/SourceFiles/overview/**-> docs/history-message-view.md -
any change to chat history widgets, message item rendering/editing/helpers, selection, unread indicators, translation, location handling, admin log, dialogs, or overview chat surfaces -> docs/history-message-view.md
-
Telegram/SourceFiles/window/**-> docs/window-shell-navigation-notifications.md -
Telegram/SourceFiles/tray*.*-> docs/window-shell-navigation-notifications.md -
Telegram/SourceFiles/tray_accounts_menu*.*-> docs/window-shell-navigation-notifications.md -
any change to main window shell, session/window controllers, navigation, adaptive layout, menus/top bars, chat switching, passcode/lock widgets, notifications, themes, or tray integration -> docs/window-shell-navigation-notifications.md
-
Telegram/SourceFiles/ui/**-> docs/ui-toolkit-controls-rendering.md -
Telegram/SourceFiles/boxes/**-> docs/ui-toolkit-controls-rendering.md -
Telegram/SourceFiles/layout/**-> docs/ui-toolkit-controls-rendering.md -
Telegram/SourceFiles/menu/**-> docs/ui-toolkit-controls-rendering.md -
Telegram/SourceFiles/inline_bots/**-> docs/ui-toolkit-controls-rendering.md -
Telegram/SourceFiles/poll/**-> docs/ui-toolkit-controls-rendering.md -
any change to shared widgets, controls, boxes/layers, text/image/effects rendering, styles, peer/userpic/unread/search components, grouped layout, menus, inline bots, or poll UI -> docs/ui-toolkit-controls-rendering.md
-
Telegram/SourceFiles/media/**-> docs/media-calls-webviews-editor.md -
Telegram/SourceFiles/calls/**-> docs/media-calls-webviews-editor.md -
Telegram/SourceFiles/editor/**-> docs/media-calls-webviews-editor.md -
Telegram/SourceFiles/ffmpeg/**-> docs/media-calls-webviews-editor.md -
Telegram/SourceFiles/webauthn/**-> docs/media-calls-webviews-editor.md -
Telegram/SourceFiles/iv/**-> docs/media-calls-webviews-editor.md -
Telegram/lib_lottie/**-> docs/media-calls-webviews-editor.md -
Telegram/lib_qr/**-> docs/media-calls-webviews-editor.md -
Telegram/lib_webrtc/**-> docs/media-calls-webviews-editor.md -
Telegram/lib_webview/**-> docs/media-calls-webviews-editor.md -
Telegram/ThirdParty/**-> docs/media-calls-webviews-editor.md -
any change to media playback/processing, calls/WebRTC, embedded webviews/web apps, webauthn, editor behavior, ffmpeg integration, QR/lottie/webview support, or related third-party library boundaries -> docs/media-calls-webviews-editor.md