Knowledge Base updated: 2026-11-19
Knowledge Base Index
1. Orientation
This repository is Ayugram for Android, a Telegram Android client fork built around TMessagesProj. The highest-level flow is: Android starts the app shell, users authenticate, tgnet exchanges Telegram API updates/requests, controllers update SQLite-backed state, and UI screens render chats, settings, media, notifications, and calls.
Main parts:
TMessagesProjAndroid app: Gradle app module, manifest, resources, Java/Kotlin-era Android code, and native JNI code.org/telegram/messenger: core runtime controllers for accounts, messages, storage coordination, media, notifications, configuration, and Android services/receivers.org/telegram/tgnetplusTMessagesProj/jni/tgnet: Telegram network protocol, TL serialization, request dispatch, and native networking bridge.org/telegram/ui: screens, fragments, navigation, theme system, reusable cells/components, chat UI, auth/settings UI, VoIP UI.com/radolyn/ayugramandcom/exteragram/messenger: fork-specific Ayugram and Exteragram features, configuration, preferences, resources, and integrations.org/webrtcandTMessagesProj/jni/voip: voice/video call bindings and native call/media support.
Critical state lives in:
- SQLite via
org/telegram/SQLite,MessagesStorage, schemas, and native sqlite wrappers: messages, dialogs, users, metadata, and persistent app data. - Android shared preferences/config classes such as
UserConfig,SharedConfig, Ayugram/Exteragram configs: account and feature settings. - File/media cache and path metadata through
FileLoader,ImageLoader,MediaController, andFilePathDatabase. - Android resources under
TMessagesProj/src/main/res*: strings, themes, XML components, raw call/animation assets, and fork-specific resource overlays.
2. Architecture diagrams
flowchart TD
subgraph AndroidApp["TMessagesProj Android app"]
Build["Gradle + Manifest"]
Startup["ApplicationLoader / LaunchActivity"]
UI["org/telegram/ui screens"]
Controllers["org/telegram/messenger controllers"]
Storage["MessagesStorage + SQLite"]
Media["File / Image / Media pipeline"]
Notify["Push / Notifications / Widgets"]
Calls["VoIP + WebRTC"]
Forks["Ayugram + Exteragram"]
end
subgraph Native["JNI / native"]
TgNetNative["jni/tgnet"]
SQLiteNative["jni/sqlite"]
MediaNative["ffmpeg / opus / rlottie / image"]
VoipNative["jni/voip"]
end
ExternalTelegram["Telegram API"]
AndroidOS["Android OS services"]
FCM["Firebase / push"]
Build --> Startup
Startup --> UI
UI --> Controllers
Forks --> UI
Forks --> Controllers
Controllers --> TgNetNative
TgNetNative --> ExternalTelegram
Controllers --> Storage
Storage --> SQLiteNative
UI --> Media
Controllers --> Media
Media --> MediaNative
FCM --> Notify
AndroidOS --> Notify
Notify --> Controllers
UI --> Calls
Calls --> VoipNative
sequenceDiagram
participant User
participant UI as ChatActivity / DialogsActivity
participant Controllers as MessagesController / SendMessagesHelper
participant Net as org.telegram.tgnet
participant API as Telegram API
participant DB as MessagesStorage / SQLite
participant Media as FileLoader / MediaController
User->>UI: opens dialog or sends message
UI->>Controllers: request dialog state or send action
Controllers->>DB: read cached messages/dialogs
Controllers->>Net: send TL request or message update
Net->>API: Telegram protocol exchange
API-->>Net: response / updates
Net-->>Controllers: parsed TLRPC objects
Controllers->>DB: persist messages and metadata
Controllers->>Media: schedule media/file work when needed
Controllers-->>UI: NotificationCenter/controller updates
UI-->>User: render updated chat state
flowchart LR
FCM["Push / FCM"] --> PushSvc["GcmPushListenerService"]
AndroidReceivers["Android receivers/actions"] --> NotifyCtrl["NotificationsController"]
PushSvc --> PushCtrl["PushListenerController"]
PushCtrl --> NotifyCtrl
NotifyCtrl --> MsgCtrl["MessagesController"]
MsgCtrl --> Storage["MessagesStorage"]
NotifyCtrl --> AndroidNotif["Android notifications"]
AndroidNotif --> Reply["reply/open/dismiss receivers"]
Widgets["Chats/Contacts/Feed widgets"] --> MsgCtrl
Reply --> MsgCtrl
flowchart TD
CallUI["VoIPFragment / GroupCallActivity"] --> VoIPService["VoIPService"]
VoIPService --> VoIPController["VoIPController / NativeInstance"]
VoIPController --> WebRTC["org/webrtc bindings"]
WebRTC --> NativeVoIP["jni/voip"]
NativeVoIP --> Network["call media/network transport"]
VoIPService --> Notifications["call notifications + audio routing"]
VoIPService --> Tgnet["tgnet signaling"]
3. Glossary
- Ayugram: fork-specific feature layer under
com/radolyn/ayugramwith custom config, handlers, sync, database, and UI integrations. - Exteragram: customization layer under
com/exteragram/messengerfor resources, preferences, icons, boost/camera/components, and utilities. TMessagesProj: the main Android application module in this repository.tgnet: Telegram network/protocol layer spanningorg/telegram/tgnetand nativeTMessagesProj/jni/tgnetcode.TLRPC: generated/maintained Telegram TL API object model used by network requests, controllers, and storage.
4. Codebase-wide invariants
- The repository is organized around a single Android app module rooted at
TMessagesProj/, with top-level Gradle files settings.gradle, build.gradle, and TMessagesProj/build.gradle providing the build shell. - Java source is rooted under
TMessagesProj/src/main/java/, with major namespaces visible asorg/telegram/**,org/webrtc/**,com/radolyn/ayugram/**, andcom/exteragram/messenger/**. - Native C/C++ support is centralized under
TMessagesProj/jni/**, including protocol, sqlite, media, and VoIP native subtrees such asjni/tgnet/**,jni/sqlite/**,jni/ffmpeg/**, andjni/voip/**. - Android resources are split between the default resource tree and fork/device overlays:
TMessagesProj/src/main/res/**,TMessagesProj/src/main/res-solar/**, andTMessagesProj/src/main/res-tabs/**. - Fork-specific user-facing strings/resources are identifiable through resource overlays such as TMessagesProj/…/ayu.xml and TMessagesProj/…/extera.xml.
5. Routing table
-
gradle.properties-> docs/android-build-app-shell.md -
gradle/**-> docs/android-build-app-shell.md -
gradlew-> docs/android-build-app-shell.md -
Dockerfile-> docs/android-build-app-shell.md -
TMessagesProj/build.gradle -> docs/android-build-app-shell.md
-
TMessagesProj/proguard-rules.pro-> docs/android-build-app-shell.md -
TMessagesProj/config/**-> docs/android-build-app-shell.md -
TMessagesProj/google-services.json -> docs/android-build-app-shell.md
-
TMessagesProj/…/AndroidManifest.xml -> docs/android-build-app-shell.md
-
TMessagesProj/src/main/assets/**-> docs/android-build-app-shell.md -
TMessagesProj/src/main/res/**-> docs/android-build-app-shell.md -
TMessagesProj/src/main/res-solar/**-> docs/android-build-app-shell.md -
TMessagesProj/src/main/res-tabs/**-> docs/android-build-app-shell.md -
TMessagesProj/…/ApplicationLoader.java -> docs/android-build-app-shell.md
-
TMessagesProj/…/BuildVars.java -> docs/android-build-app-shell.md
-
TMessagesProj/…/NativeLoader.java -> docs/android-build-app-shell.md
-
TMessagesProj/…/LaunchActivity.java -> docs/android-build-app-shell.md
-
TMessagesProj/…/IntroActivity.java -> docs/android-build-app-shell.md
-
any change to Android packaging, manifest-declared components, resource overlays, build variants, signing config, or app startup -> docs/android-build-app-shell.md
-
TMessagesProj/src/main/java/org/telegram/tgnet/**-> docs/tgnet-networking.md -
TMessagesProj/jni/tgnet/**-> docs/tgnet-networking.md -
TMessagesProj/…/TgNetWrapper.cpp -> docs/tgnet-networking.md
-
TMessagesProj/…/NativeLoader.cpp -> docs/tgnet-networking.md
-
any Telegram TL schema, request delegate, serialization, connection, quick-ack, or Java/native protocol bridge change -> docs/tgnet-networking.md
-
TMessagesProj/…/AccountInstance.java -> docs/messaging-domain-controllers.md
-
TMessagesProj/…/BaseController.java -> docs/messaging-domain-controllers.md
-
TMessagesProj/…/MessagesController.java -> docs/messaging-domain-controllers.md
-
TMessagesProj/…/SendMessagesHelper.java -> docs/messaging-domain-controllers.md
-
TMessagesProj/…/MessageObject.java -> docs/messaging-domain-controllers.md
-
TMessagesProj/…/ChatObject.java -> docs/messaging-domain-controllers.md
-
TMessagesProj/…/DialogObject.java -> docs/messaging-domain-controllers.md
-
TMessagesProj/…/UserObject.java -> docs/messaging-domain-controllers.md
-
TMessagesProj/…/UserConfig.java -> docs/messaging-domain-controllers.md
-
TMessagesProj/…/SharedConfig.java -> docs/messaging-domain-controllers.md
-
TMessagesProj/…/MediaDataController.java -> docs/messaging-domain-controllers.md
-
TMessagesProj/…/ContactsController.java -> docs/messaging-domain-controllers.md
-
TMessagesProj/…/DownloadController.java -> docs/messaging-domain-controllers.md
-
TMessagesProj/…/TopicsController.java -> docs/messaging-domain-controllers.md
-
TMessagesProj/…/ChatMessagesMetadataController.java -> docs/messaging-domain-controllers.md
-
TMessagesProj/…/MemberRequestsController.java -> docs/messaging-domain-controllers.md
-
TMessagesProj/…/NotificationCenter.java -> docs/messaging-domain-controllers.md
-
TMessagesProj/…/Utilities.java -> docs/messaging-domain-controllers.md
-
TMessagesProj/…/AndroidUtilities.java -> docs/messaging-domain-controllers.md
-
TMessagesProj/…/DispatchQueue*.java -> docs/messaging-domain-controllers.md
-
any change to account-scoped message/chat/user/topic controllers, send/update fan-out, or
NotificationCenterevent delivery -> docs/messaging-domain-controllers.md -
TMessagesProj/src/main/java/org/telegram/SQLite/**-> docs/storage-and-sqlite.md -
TMessagesProj/…/MessagesStorage.java -> docs/storage-and-sqlite.md
-
TMessagesProj/…/DatabaseMigrationHelper.java -> docs/storage-and-sqlite.md
-
TMessagesProj/…/FilePathDatabase.java -> docs/storage-and-sqlite.md
-
TMessagesProj/…/FilesMigrationService.java -> docs/storage-and-sqlite.md
-
TMessagesProj/schemas/**-> docs/storage-and-sqlite.md -
TMessagesProj/jni/sqlite/**-> docs/storage-and-sqlite.md -
TMessagesProj/…/SqliteWrapper.cpp -> docs/storage-and-sqlite.md
-
any DB schema, migration, cursor/prepared-statement, message persistence, or file path database change -> docs/storage-and-sqlite.md
-
TMessagesProj/…/MediaController.java -> docs/files-media-pipeline.md
-
TMessagesProj/…/DocumentObject.java -> docs/files-media-pipeline.md
-
TMessagesProj/…/DownloadObject.java -> docs/files-media-pipeline.md
-
TMessagesProj/…/AnimatedFileDrawableStream.java -> docs/files-media-pipeline.md
-
TMessagesProj/…/VideoEditedInfo.java -> docs/files-media-pipeline.md
-
TMessagesProj/…/VideoEncodingService.java -> docs/files-media-pipeline.md
-
TMessagesProj/src/main/java/org/telegram/messenger/audioinfo/**-> docs/files-media-pipeline.md -
TMessagesProj/src/main/java/org/telegram/messenger/camera/**-> docs/files-media-pipeline.md -
TMessagesProj/src/main/java/org/telegram/messenger/video/**-> docs/files-media-pipeline.md -
TMessagesProj/src/main/java/org/telegram/messenger/secretmedia/**-> docs/files-media-pipeline.md -
TMessagesProj/…/gifvideo.cpp -> docs/files-media-pipeline.md
-
TMessagesProj/jni/ffmpeg/**-> docs/files-media-pipeline.md -
TMessagesProj/jni/exoplayer/**-> docs/files-media-pipeline.md -
TMessagesProj/jni/libwebp/**-> docs/files-media-pipeline.md -
TMessagesProj/jni/mozjpeg/**-> docs/files-media-pipeline.md -
TMessagesProj/jni/opus/**-> docs/files-media-pipeline.md -
TMessagesProj/jni/rlottie/**-> docs/files-media-pipeline.md -
any upload/download/cache, image decode, video encode, camera, audio metadata, sticker/animation rendering, or native media codec change -> docs/files-media-pipeline.md
-
TMessagesProj/…/*Push*.java -> docs/notifications-push-widgets.md
-
TMessagesProj/…/*Notification*.java -> docs/notifications-push-widgets.md
-
TMessagesProj/…/GcmPushListenerService.java -> docs/notifications-push-widgets.md
-
TMessagesProj/…/Notifications*.java -> docs/notifications-push-widgets.md
-
TMessagesProj/…/PopupReplyReceiver.java -> docs/notifications-push-widgets.md
-
TMessagesProj/…/AutoMessage*.java -> docs/notifications-push-widgets.md
-
TMessagesProj/…/OpenChatReceiver.java -> docs/notifications-push-widgets.md
-
TMessagesProj/…/ShareBroadcastReceiver.java -> docs/notifications-push-widgets.md
-
TMessagesProj/…/ScreenReceiver.java -> docs/notifications-push-widgets.md
-
TMessagesProj/…/KeepAliveJob.java -> docs/notifications-push-widgets.md
-
TMessagesProj/…/ChatsWidget*.java -> docs/notifications-push-widgets.md
-
TMessagesProj/…/ContactsWidget*.java -> docs/notifications-push-widgets.md
-
TMessagesProj/…/FeedWidget*.java -> docs/notifications-push-widgets.md
-
TMessagesProj/…/PopupNotificationActivity.java -> docs/notifications-push-widgets.md
-
TMessagesProj/…/Notifications*.java -> docs/notifications-push-widgets.md
-
TMessagesProj/…/ProfileNotificationsActivity.java -> docs/notifications-push-widgets.md
-
TMessagesProj/…/*Widget*.java -> docs/notifications-push-widgets.md
-
TMessagesProj/…/*widget*.xml -> docs/notifications-push-widgets.md
-
TMessagesProj/…/shortcuts.xml -> docs/notifications-push-widgets.md
-
any push receipt, notification action/reply/dismiss, notification setting, background keepalive, shortcut, or widget update change -> docs/notifications-push-widgets.md
-
TMessagesProj/src/main/java/org/telegram/ui/ActionBar/**-> docs/ui-navigation-theme-shell.md -
TMessagesProj/src/main/java/org/telegram/ui/Components/**-> docs/ui-navigation-theme-shell.md -
TMessagesProj/src/main/java/org/telegram/ui/Cells/**-> docs/ui-navigation-theme-shell.md -
TMessagesProj/src/main/java/org/telegram/ui/Adapters/**-> docs/ui-navigation-theme-shell.md -
TMessagesProj/src/main/java/org/telegram/ui/Delegates/**-> docs/ui-navigation-theme-shell.md -
TMessagesProj/src/main/java/org/telegram/ui/Storage/**-> docs/ui-navigation-theme-shell.md -
TMessagesProj/src/main/java/org/telegram/ui/LNavigation/**-> docs/ui-navigation-theme-shell.md -
TMessagesProj/…/Theme*.java -> docs/ui-navigation-theme-shell.md
-
TMessagesProj/…/BasePermissionsActivity.java -> docs/ui-navigation-theme-shell.md
-
TMessagesProj/…/DialogsActivity.java -> docs/ui-navigation-theme-shell.md
-
TMessagesProj/…/ProfileActivity.java -> docs/ui-navigation-theme-shell.md
-
TMessagesProj/…/ContactsActivity.java -> docs/ui-navigation-theme-shell.md
-
TMessagesProj/…/LanguageSelectActivity.java -> docs/ui-navigation-theme-shell.md
-
TMessagesProj/…/WallpapersListActivity.java -> docs/ui-navigation-theme-shell.md
-
TMessagesProj/…/ArticleViewer.java -> docs/ui-navigation-theme-shell.md
-
TMessagesProj/…/PhotoViewer.java -> docs/ui-navigation-theme-shell.md
-
any UI navigation, fragment stack, action bar, reusable component/cell, adapter, theme, or shared visual foundation change -> docs/ui-navigation-theme-shell.md
-
TMessagesProj/…/ChatActivity.java -> docs/chat-screen-message-flow.md
-
TMessagesProj/…/Chat*.java -> docs/chat-screen-message-flow.md
-
TMessagesProj/…/Topic*.java -> docs/chat-screen-message-flow.md
-
TMessagesProj/…/Topics*.java -> docs/chat-screen-message-flow.md
-
TMessagesProj/…/DialogsActivity.java -> docs/chat-screen-message-flow.md
-
TMessagesProj/…/Chat*.java -> docs/chat-screen-message-flow.md
-
TMessagesProj/…/Dialog*.java -> docs/chat-screen-message-flow.md
-
TMessagesProj/…/Chat*.java -> docs/chat-screen-message-flow.md
-
TMessagesProj/…/Dialogs*.java -> docs/chat-screen-message-flow.md
-
TMessagesProj/…/MentionsContainerView.java -> docs/chat-screen-message-flow.md
-
TMessagesProj/…/Message*.java -> docs/chat-screen-message-flow.md
-
TMessagesProj/…/EmbedBottomSheet.java -> docs/chat-screen-message-flow.md
-
TMessagesProj/…/FilteredSearchView.java -> docs/chat-screen-message-flow.md
-
TMessagesProj/…/Filter*.java -> docs/chat-screen-message-flow.md
-
TMessagesProj/…/Filters*.java -> docs/chat-screen-message-flow.md
-
TMessagesProj/…/ShareActivity.java -> docs/chat-screen-message-flow.md
-
any dialog list, chat screen, topic, message cell, composer, attachment panel, mentions, search/filter, or share-to-chat flow change -> docs/chat-screen-message-flow.md
-
TMessagesProj/…/LoginActivity.java -> docs/auth-accounts-settings.md
-
TMessagesProj/…/PasscodeActivity.java -> docs/auth-accounts-settings.md
-
TMessagesProj/…/TwoStepVerification*.java -> docs/auth-accounts-settings.md
-
TMessagesProj/…/SessionsActivity.java -> docs/auth-accounts-settings.md
-
TMessagesProj/…/SessionBottomSheet.java -> docs/auth-accounts-settings.md
-
TMessagesProj/…/LogoutActivity.java -> docs/auth-accounts-settings.md
-
TMessagesProj/…/Privacy*.java -> docs/auth-accounts-settings.md
-
TMessagesProj/…/Data*.java -> docs/auth-accounts-settings.md
-
TMessagesProj/…/Proxy*.java -> docs/auth-accounts-settings.md
-
TMessagesProj/…/Change*.java -> docs/auth-accounts-settings.md
-
TMessagesProj/…/Settings*.java -> docs/auth-accounts-settings.md
-
TMessagesProj/…/QuickRepliesSettingsActivity.java -> docs/auth-accounts-settings.md
-
TMessagesProj/…/AuthenticatorService.java -> docs/auth-accounts-settings.md
-
TMessagesProj/…/AuthTokensHelper.java -> docs/auth-accounts-settings.md
-
TMessagesProj/…/ContactsSyncAdapterService.java -> docs/auth-accounts-settings.md
-
TMessagesProj/…/LocaleController.java -> docs/auth-accounts-settings.md
-
TMessagesProj/…/ProxyRotationController.java -> docs/auth-accounts-settings.md
-
TMessagesProj/…/SharedPrefsHelper.java -> docs/auth-accounts-settings.md
-
TMessagesProj/…/SmsReceiver.java -> docs/auth-accounts-settings.md
-
TMessagesProj/…/contacts.xml -> docs/auth-accounts-settings.md
-
TMessagesProj/…/strings.xml -> docs/auth-accounts-settings.md
-
any login, SMS/auth token, passcode, two-step verification, session, logout, privacy, data/autodownload, proxy, localization, account sync, or settings screen change -> docs/auth-accounts-settings.md
-
TMessagesProj/src/main/java/org/telegram/messenger/voip/**-> docs/voip-and-webrtc-calls.md -
TMessagesProj/…/GroupCall*.java -> docs/voip-and-webrtc-calls.md
-
TMessagesProj/…/GroupCall*.java -> docs/voip-and-webrtc-calls.md
-
TMessagesProj/…/JoinCall*.java -> docs/voip-and-webrtc-calls.md
-
TMessagesProj/src/main/java/org/webrtc/**-> docs/voip-and-webrtc-calls.md -
TMessagesProj/jni/voip/**-> docs/voip-and-webrtc-calls.md -
TMessagesProj/src/main/res/raw/voip_*-> docs/voip-and-webrtc-calls.md -
TMessagesProj/src/main/res/raw/voicechat_*-> docs/voip-and-webrtc-calls.md -
any one-to-one call, group call, WebRTC binding, native VoIP, call notification/audio routing, or call UI change -> docs/voip-and-webrtc-calls.md
-
TMessagesProj/src/main/java/com/radolyn/ayugram/**-> docs/ayugram-custom-features.md -
any Ayugram config, custom handler/filter/forwarding, Ayugram database/sync, proprietary/easy/messages package, or Ayugram UI utility change -> docs/ayugram-custom-features.md
-
TMessagesProj/src/main/java/com/exteragram/messenger/**-> docs/exteragram-customizations.md -
TMessagesProj/…/extera.xml -> docs/exteragram-customizations.md
-
TMessagesProj/src/main/res/drawable*/extera*-> docs/exteragram-customizations.md -
TMessagesProj/src/main/res/mipmap*/extera*-> docs/exteragram-customizations.md -
any Exteragram config/resource, preference, icon, boost, camera, component, or utility change -> docs/exteragram-customizations.md