Android build and app shell
Overview
This doc owns the Android Gradle project shell and the runtime entry surface that turns the built package into the running AyuGram/Telegram app:
- Root build configuration: build.gradle, settings.gradle,
gradle.properties,gradle/**,gradlew,Dockerfile, crowdin.yml. - App build and packaging: TMessagesProj/build.gradle,
TMessagesProj/proguard-rules.pro,TMessagesProj/config/**, TMessagesProj/google-services.json. - Runtime app surface: TMessagesProj/…/AndroidManifest.xml,
TMessagesProj/src/main/assets/**,TMessagesProj/src/main/res/**,TMessagesProj/src/main/res-solar/**,TMessagesProj/src/main/res-tabs/**, TMessagesProj/…/ApplicationLoader.java, BuildVars.java, NativeLoader.java, TMessagesProj/…/LaunchActivity.java, and IntroActivity.java.
The repository is a single-module Android project. settings.gradle includes only :TMessagesProj; the root build.gradle pins Android Gradle Plugin 7.4.2, Google services, and Firebase Crashlytics plugins. gradle/wrapper/gradle-wrapper.properties points the wrapper at Gradle 7.5.1. gradle.properties supplies the published app identity knobs (APP_VERSION_NAME, APP_VERSION_CODE, APP_PACKAGE=com.radolyn.ayugram) plus AndroidX, Jetifier, R8, non-transitive R, and resource shrinker settings consumed by TMessagesProj/build.gradle.
TMessagesProj/build.gradle applies com.android.application, declares the Android namespace org.telegram.messenger, and assigns defaultConfig.applicationId, versionName, and versionCode from gradle.properties. It reads an optional root API_KEYS file for generated BuildConfig values (APP_ID, APP_HASH, AYU_VERSION) and the MAPS_V2_API resource. Native code is built through jni/CMakeLists.txt with NDK 21.4.7075529, min SDK 21, target/compile SDK 33, Java 11, and src/main/res, src/main/res-solar, and src/main/res-tabs all merged as app resources. Release and debug are both multidex builds signed with TMessagesProj/config/extera.jks; release enables minification and resource shrinking, while debug disables both and sets BuildConfig.DEBUG_VERSION=true.
Packaging is ABI-flavored. armv7, x86, arm64, and x64 build single-ABI APKs; afat builds a four-ABI package and uses TMessagesProj/…/AndroidManifest.xml as an additional manifest; beta builds two ABIs and uses TMessagesProj/…/AndroidManifest.xml. variantFilter keeps beta as debug-only and all non-beta flavors as release-only. Output APK names are ayuGram[-beta]-<abi>-<ddMMyyyy>.apk, and the per-output version code is APP_VERSION_CODE * 10 + abiVersionCode unless isPmBuild is set. Dockerfile provides a reproducible-ish build container using Gradle/JDK 11, Android SDK 33, build tools 33.0.0 plus 30.0.3 dx compatibility copies, NDK 21.4.7075529, and runs bundle/assemble tasks for afat, afat_SDK23, and standalone outputs.
TMessagesProj/…/AndroidManifest.xml is the main runtime contract. The <application> class is .ApplicationLoader, the startup theme is @style/Theme.TMessages.Start, and the manifest declares the permissions and components used across messaging, contacts sync, file sharing, widgets, media playback, calls, Firebase, maps, billing, notifications, and install referrers. Launcher visibility is mostly through multiple activity-alias declarations (com.exteragram.messenger.DefaultIcon, MonetIcon, GradientIcon, etc.) targeting org.telegram.ui.LaunchActivity; those aliases are what alternate launcher icon logic toggles. LaunchActivity also owns SEND/SEND_MULTIPLE, http(s) Telegram hosts (telegram.me, telegram.dog, t.me), tg: deep links, sticker-pack import, chooser share targets, and app shortcut metadata via TMessagesProj/…/shortcuts.xml. TMessagesProj/…/AndroidManifest.xml and TMessagesProj/…/AndroidManifest.xml add flavor-specific icons/labels, Google/Firebase push service declarations, location/maps permissions, exact alarm, and the ${applicationId}.permission.MAPS_RECEIVE signature permission; the SDK23 and standalone config manifests are currently empty placeholders.
Startup is split between ApplicationLoader and LaunchActivity. Android creates ApplicationLoader from the manifest, attachBaseContext() installs multidex, and onCreate() captures applicationContext, loads native library tmessages.45 through NativeLoader.initNativeLibs(), calls ConnectionsManager.native_setJava(false), installs foreground detection, a debug crash clipboard handler, starts the notification service on the UI thread, repairs launcher icon aliases through LauncherIconController.tryFixLauncherIconIfNeeded(), initializes proxy rotation, and initializes Firebase Analytics/Crashlytics according to ExteraConfig. ApplicationLoader.postInitApplication() is intentionally deferred until LaunchActivity.onCreate(): it loads locale/config state, registers network and screen receivers, loads per-account UserConfig, instantiates controllers (MessagesController, ContactsController, DownloadController, MediaController, BillingController), requests push registration, and starts Ayu sync via AyuSyncController.create().
NativeLoader.java is the native runtime bridge for the build’s C/C++ outputs. It first calls System.loadLibrary("tmessages.45"); if that fails, it derives an ABI folder from Build.CPU_ABI, extracts lib/<abi>/libtmessages.45.so from the APK into files/lib/libtmessages.45loc.so, and loads that path. If native packaging or ABI filters in TMessagesProj/build.gradle change, this loader is the code that will surface missing-library failures during ApplicationLoader.onCreate().
BuildVars.java is the Java-facing build constant adapter. It maps generated BuildConfig values to app-wide constants (DEBUG_VERSION, PM_BUILD, BUILD_VERSION, BUILD_VERSION_STRING, AYU_VERSION, APP_ID, APP_HASH) and hard-codes behavior such as isStandaloneApp() == true, CHECK_UPDATES == false, USE_CLOUD_STRINGS == true, Play Store URL, Google auth client ID, and SMS retriever hashes keyed by debug-vs-release. Code outside this doc should treat BuildVars as the boundary between Gradle/package identity and runtime feature decisions.
LaunchActivity.java is the UI and intent router behind the launcher aliases. onCreate() calls ApplicationLoader.postInitApplication(), sets Theme.TMessages, builds the navigation containers/drawer/tablet layouts, selects the first fragment, and then calls handleIntent(getIntent(), ...). If the selected account is not activated, it pushes IntroActivity or LoginActivity depending on saved login state; otherwise it pushes DialogsActivity. handleIntent() switches to the requested account, gates work behind passcode unlock when needed, parses external share payloads into media/text/contact fields, parses http(s) Telegram links and tg: schemes into navigation targets, and opens chat/profile/settings/call/search/import flows via the navigation layouts.
IntroActivity.java is the first-run fragment selected by LaunchActivity for non-activated clients. It builds the onboarding UI from TMessagesProj/…/strings.xml keys such as Page1Message, Page2Title, and StartMessaging, renders its animated pages with OpenGL textures loaded from TMessagesProj/src/main/res/drawable*, and advances to LoginActivity when the start button is pressed. It also offers a suggested-language path by applying LocaleController language changes before opening login.
Resources and assets are part of this shell because they are either packaged by Gradle or referenced directly by the manifest/startup classes. TMessagesProj/…/styles.xml defines Theme.TMessages.Start, Theme.TMessages, transparent/popup variants, widget styles, and startup action-bar styling. TMessagesProj/…/bools.xml controls manifest-level hardware acceleration via @bool/useHardwareAcceleration, with API-qualified overrides under values-v14, values-v15, and values-v16. TMessagesProj/…/extera.xml contains the app label exteraAppName used by config manifests plus exteraGram strings; TMessagesProj/…/ayu.xml contains AyuGram preference strings and is the only Crowdin source configured in crowdin.yml. TMessagesProj/…/provider_paths.xml, auth.xml, sync_contacts.xml, widget XML, automotive actions, and shortcuts XML are consumed by manifest providers/services/metadata. TMessagesProj/src/main/res-solar/** is an alternate Solar icon drawable pack merged into normal resources, while TMessagesProj/src/main/res-tabs/** supplies filter tab icons in density buckets. TMessagesProj/src/main/assets/** packages non-resource payloads such as theme files (night.attheme, monet_*.attheme), fonts, emoji sheets, shader GLSL, youtube_embed.html, OCR data, and model binaries.
For routing future reviews: changes to Gradle/plugins/wrapper/Dockerfile/API key generation belong here; changes to manifest permissions/components/intent filters/aliases belong here; changes to app labels, launcher icons, startup themes, shortcuts, provider XML, assets, Solar/tab resources, or onboarding resources belong here. Business logic inside controllers, message storage, networking, sync, billing, notifications, UI screens beyond launcher/onboarding, and native implementation code are outside this doc unless the change alters how this shell invokes or packages them.
Coupling
- If
APP_PACKAGEingradle.propertiesordefaultConfig.applicationIdin TMessagesProj/build.gradle changes, also update TMessagesProj/google-services.json, manifest authorities using${applicationId}in TMessagesProj/…/AndroidManifest.xml, and any hard-coded package fallback such asApplicationLoader.getFilesDirFixed()returning/data/data/com.radolyn.ayugram/files. - If
APP_VERSION_CODE, flavorabiVersionCode, orisPmBuildlogic in TMessagesProj/build.gradle changes, verify update/install compatibility: the effective APK version code is overridden per output, not justdefaultConfig.versionCode. - If ABI filters, NDK version, native library name/version, or CMake packaging changes in TMessagesProj/build.gradle, verify NativeLoader.java still looks for the same
lib/<abi>/libtmessages.45.sopath and thatApplicationLoader.onCreate()can completeConnectionsManager.native_setJava(false)on every produced flavor. - If a launcher alias is added, removed, renamed, or given a new icon in TMessagesProj/…/AndroidManifest.xml, check the launcher-icon switching code referenced by
ApplicationLoader.onCreate()(LauncherIconController.tryFixLauncherIconIfNeeded()) and the corresponding@mipmap/ic_launcher_*resources. Disabled aliases are still part of the app’s public launcher contract. - If intent filters in TMessagesProj/…/AndroidManifest.xml change for SEND/SEND_MULTIPLE,
tg:,tgb:, Telegram web hosts, sticker import, chooser targets, or Passport authorization, update the parser inLaunchActivity.handleIntent(); Android may route an intent that the parser silently treats as unsupported or vice versa. - If TMessagesProj/…/shortcuts.xml or direct-share categories change, verify
LaunchActivity.handleIntent()still resolvesShortcutManagerCompat.EXTRA_SHORTCUT_ID,dialogId, andSharedConfig.directShareHashfor share targets. - If Firebase, Maps, Location, or Push dependencies are changed in TMessagesProj/build.gradle, also check TMessagesProj/…/AndroidManifest.xml, TMessagesProj/…/AndroidManifest.xml, TMessagesProj/google-services.json,
ApplicationLoader.onCreateLocationServiceProvider(),onCreateMapsProvider(),onCreatePushProvider(), andApplicationLoader.initFirebase(); these providers are instantiated from the application shell before most UI is visible. - If resource source sets in TMessagesProj/build.gradle change, verify references from
LaunchActivity,IntroActivity, and TMessagesProj/…/AndroidManifest.xml still resolve.res-solarandres-tabsare not standalone modules; they are merged resource roots. - If BuildVars.java constants are changed, check both Gradle-generated fields in TMessagesProj/build.gradle and runtime call sites.
BuildVars.DEBUG_VERSIONcontrols debug crash handling and beta behavior,BuildVars.PM_BUILDdisables billing viaIS_BILLING_UNAVAILABLE, andAPP_ID/APP_HASHare generated from the localAPI_KEYSfile.
Risks
- TMessagesProj/build.gradle signs both debug and release with
TMessagesProj/config/extera.jksand passwords from a rootAPI_KEYSfile. If that keystore or the expected local properties are missing, even debug variants can fail to sign; if the keystore changes, Firebase OAuth/SMS-related configuration in TMessagesProj/google-services.json andBuildVars.SMS_HASHmay no longer match installed packages. - TMessagesProj/…/AndroidManifest.xml sets
android:usesCleartextTraffic="true"on the main application despite an inline note to remove it for release. If this remains in release builds, network security policy permits cleartext traffic for the app package. ApplicationLoader.startPushService()creates aPendingIntentwithPendingIntent.getBroadcast(applicationContext, 0, new Intent(applicationContext, NotificationsService.class), ...)even thoughNotificationsServiceis declared as a service in TMessagesProj/…/AndroidManifest.xml. If the keep-alive alarm path is relied on, verify it actually starts or cancels the intended component on target Android versions.- NativeLoader.java derives the extraction ABI from
Build.CPU_ABIand falls back toarmeabifor unknown architectures, while TMessagesProj/build.gradle only buildsarmeabi-v7a,arm64-v8a,x86, andx86_64. If a produced APK is installed on an unsupported or misreported ABI, startup can fail before UI withcan't load native librariesfromApplicationLoader.onCreate().