If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/DrKLO/Telegram shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Mixed signals — read the receipts

• Last commit 4w ago
• 3 active contributors
• Distributed ownership (top contributor 35% of recent commits)
• GPL-2.0 licensed
• Tests present
• ⚠ Small team — 3 contributors active in recent commits
• ⚠ GPL-2.0 is copyleft — check downstream compatibility
• ⚠ No CI workflows detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live DrKLO/Telegram repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/DrKLO/Telegram.

What it runs against: a local clone of DrKLO/Telegram — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in DrKLO/Telegram | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 61 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of DrKLO/Telegram. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/DrKLO/Telegram.git
#   cd Telegram
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of DrKLO/Telegram and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "DrKLO/Telegram(\\.git)?\\b" \\
  && ok "origin remote is DrKLO/Telegram" \\
  || miss "origin remote is not DrKLO/Telegram (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(GPL-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"GPL-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is GPL-2.0" \\
  || miss "license drift — was GPL-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "TMessagesProj/build.gradle" \\
  && ok "TMessagesProj/build.gradle" \\
  || miss "missing critical file: TMessagesProj/build.gradle"
test -f "TMessagesProj/jni/CMakeLists.txt" \\
  && ok "TMessagesProj/jni/CMakeLists.txt" \\
  || miss "missing critical file: TMessagesProj/jni/CMakeLists.txt"
test -f "TMessagesProj/jni/NativeLoader.cpp" \\
  && ok "TMessagesProj/jni/NativeLoader.cpp" \\
  || miss "missing critical file: TMessagesProj/jni/NativeLoader.cpp"
test -f "TMessagesProj/jni/boringssl/CMakeLists.txt" \\
  && ok "TMessagesProj/jni/boringssl/CMakeLists.txt" \\
  || miss "missing critical file: TMessagesProj/jni/boringssl/CMakeLists.txt"
test -f "TMessagesProj/config/release/AndroidManifest.xml" \\
  && ok "TMessagesProj/config/release/AndroidManifest.xml" \\
  || miss "missing critical file: TMessagesProj/config/release/AndroidManifest.xml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 61 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~31d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/DrKLO/Telegram"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Official Telegram messenger Android application source code (~75k LOC Java, 56k LOC C++). Delivers end-to-end encrypted messaging, VoIP, media sharing, and MTProto protocol implementation compiled to native libraries via NDK rev. 20. Solves secure, fast mobile messaging by bundling BoringSSL crypto, custom MTProto networking, and TgNet wrapper layers. Hybrid Android+JNI layout: TMessagesProj/src/main/ contains Java UI and Telegram API client code; TMessagesProj/jni/ holds C++ wrappers (NativeLoader.cpp, TgNetWrapper.cpp, SqliteWrapper.cpp) and bundled BoringSSL crypto library; TMessagesProj/config/{debug,release}/ manages AndroidManifest variants and keystore. CMakeLists.txt orchestrates NDK compilation of crypto and protocol layers.

Android developers building forks or custom Telegram clients who need the canonical implementation as reference; mobile security researchers studying MTProto and E2E encryption; Telegram API developers integrating bot/channel features into their own Android apps.

Production-ready and actively maintained. This is the official Telegram for Android distributed on Google Play (org.telegram.messenger). Large codebase (~3.8 GB across Java/C++/C), substantial third-party dependencies (Firebase, Play Services, BoringSSL), regular updates implied by version management in gradle.properties. High confidence this is production code serving millions of users.

Moderate risk from complexity: requires Android NDK rev. 20 specifically (brittle), sensitive keystore and Firebase credentials must be injected (TMessagesProj/config/release.keystore, google-services.json), and BuildVars.java contains API secrets that must be replaced. Monolithic structure means changes to JNI layer (TMessagesProj/jni/CMakeLists.txt) affect entire build. No visible git history in snapshot, so hidden technical debt is unknown.

Actively maintained per README compilation guide references Android Studio 3.4+ and NDK rev. 20. Build configuration splits debug/release with SDK23+ variants (AndroidManifest_SDK23.xml), suggesting recent targeting of modern Android versions. Firebase integration (google-services.json, firebase-messaging, firebase-config) indicates ongoing push notification and feature flag infrastructure work.

git clone https://github.com/DrKLO/Telegram.git && cd Telegram/TMessagesProj && cat config/debug/AndroidManifest.xml # review structure. Install Android NDK rev. 20 via SDK Manager. Open TMessagesProj in Android Studio 3.4+ (Open, not Import). Edit TMessagesProj/src/main/java/org/telegram/messenger/BuildVars.java with your API_ID. Run: ./gradlew build

Daily commands: Android Studio: Open → TMessagesProj → File → Sync Gradle. Edit gradle.properties with RELEASE_KEY_PASSWORD, RELEASE_KEY_ALIAS, RELEASE_STORE_PASSWORD. Run → Edit Configurations → select 'TMessagesProj' → Run on emulator/device. Or: ./gradlew :TMessagesProj:assembleDebug (builds APK to TMessagesProj/build/outputs/apk/debug/).

• TMessagesProj/build.gradle — Main Gradle build configuration defining all dependencies, Android SDK versions, and build variants for the entire Telegram app
• TMessagesProj/jni/CMakeLists.txt — CMake build system for native C/C++ modules including BoringSSL crypto, TgNet networking, and SQLite wrappers
• TMessagesProj/jni/NativeLoader.cpp — JNI bridge entry point that loads and initializes all native libraries required by the Android app
• TMessagesProj/jni/boringssl/CMakeLists.txt — BoringSSL cryptographic library build configuration—critical for all MTProto protocol encryption and TLS
• TMessagesProj/config/release/AndroidManifest.xml — Release build manifest declaring all app permissions, activities, services, and API key configuration for Play Store distribution
• TMessagesProj/google-services.json — Firebase service credentials for Google Cloud messaging and analytics integration
• TMessagesProj/jni/TgNetWrapper.cpp — Native wrapper for TgNet MTProto network protocol implementation—handles all Telegram server communication

Add a new cryptographic primitive or cipher

1. Implement the cipher algorithm in C/C++ under TMessagesProj/jni/boringssl/crypto/<module>/ (TMessagesProj/jni/boringssl/crypto/[new_cipher_name]/[impl].cc)
2. Register the new cipher in BoringSSL's CMakeLists.txt source lists (TMessagesProj/jni/boringssl/CMakeLists.txt)
3. Create JNI wrapper functions in TgNetWrapper or dedicated wrapper file (TMessagesProj/jni/TgNetWrapper.cpp)
4. Update Gradle dependencies if the cipher requires external libraries (TMessagesProj/build.gradle)

Add a new network protocol feature or MTProto handler

1. Implement protocol handler in the TgNet native library source (typically in jni/ directory) (TMessagesProj/jni/TgNetWrapper.cpp)
2. Define JNI method signatures to expose the handler to Java/Kotlin (TMessagesProj/jni/TgNetWrapper.cpp)
3. Update CMakeLists.txt to include new source files in the build (TMessagesProj/jni/CMakeLists.txt)
4. Re-export native library in NativeLoader to ensure initialization (TMessagesProj/jni/NativeLoader.cpp)

Integrate a new external native library

1. Add library source or CMake find_package() declaration in root CMakeLists.txt (TMessagesProj/jni/CMakeLists.txt)
2. Link the library target to the main telegram-core target (TMessagesProj/jni/CMakeLists.txt)
3. Create or update a wrapper .cpp file to expose the library via JNI if needed (TMessagesProj/jni/[LibraryName]Wrapper.cpp)
4. Declare the new .so library in build.gradle if distributing prebuilt binaries (TMessagesProj/build.gradle)

Update build configuration or add a new compile variant

1. Add buildTypes, productFlavors, or flavorDimensions block to gradle configuration (TMessagesProj/build.gradle)
2. Create variant-specific AndroidManifest.xml in TMessagesProj/config/[variant]/ (TMessagesProj/config/[variant]/AndroidManifest.xml)
3. Define variant-specific native library settings in Application.mk or CMakeLists.txt (TMessagesProj/jni/Application.mk)
4. Sync gradle and verify the new variant appears in Android Studio's build selector (TMessagesProj/build.gradle)

• BoringSSL — Google's OpenSSL fork provides modern, hardened cryptography (AES-GCM, ChaCha20, ECDH) with constant-time implementations resistant to timing attacks; essential for MTProto security
• JNI (Java Native Interface) — Bridges Kotlin/Java Android UI layer with high-performance C/C++ networking and crypto; avoids Dalvik/ART overhead for latency-sensitive protocol operations
• CMake + NDK — Enables cross-platform ARM/x86 native compilation; CMake unifies BoringSSL and TgNet builds with consistent toolchain management across architectures
• SQLite (via JNI wrapper) — Embedded relational database for offline-first message, contact, and chat history storage; avoids network dependency for critical data
• AndroidX libraries — Provides backward-compatible UI, biometric authentication, dynamic animations, and EXIF metadata handling across Android versions 5.0+
• Firebase Cloud Messaging — Enables push notifications for incoming messages on Android devices; integrated via google-services.json for credential management

• Encrypt messaging in native C++ (TgNet) rather than pure Java

  • Why: Native code executes 5–10× faster; reduces battery drain and network latency for message encryption/decryption
  • Consequence: Increases complexity: requires JNI, NDK toolchain setup, and per-architecture binary maintenance; harder to audit and port to new platforms

• Use MTProto 2.0 custom protocol instead of standard HTTPS/gRPC

  • Why: MTProto is optimized for mobile latency and bandwidth; supports protocol obfuscation and transparent proxies for censored regions
  • Consequence: Custom protocol is not interoperable with standard HTTP clients; requires complete custom networking stack (TgNet)

• Embed BoringSSL source instead of using system OpenSSL or BouncyCastle

  • Why: Guarantees same cryptographic behavior across all Android versions; avoids vendor SSL library inconsistencies and potential weaknesses
  • Consequence: Large binary size (~2–3 MB for crypto alone); requires manual updates when BoringSSL patches are released

• Local-first SQLite storage with eventual sync to server

  • Why: Enables full offline access to chat history and contacts; removes strict network dependency for critical reads
  • Consequence: Requires conflict resolution and multi-device sync logic; can cause temporary inconsistency if device loses connection mid-sync

• Not a web or desktop application—Android-specific only
• Does not implement VoIP or video calling in this native layer (separate codecs/frameworks used)
• Does not enforce mandatory end-to-end encryption for group chats (opt-in Secret Chats only)
• Not a standalone library—tightly coupled to Telegram's proprietary MTProto protocol and infrastructure

1. NDK version pinning: Requires Android NDK rev. 20 exactly; newer/older revisions will cause CMake compilation failures. Check $ANDROID_NDK_ROOT/source.properties. 2. Secrets in BuildVars.java: Build completes but crashes at runtime if API_ID/API_HASH not set; no compile-time validation. 3. BoringSSL static linking: Changing boringssl/CMakeLists.txt requires full rebuild; incremental builds may fail. 4. Firebase credentials: google-services.json must match package names (org.telegram.messenger, org.telegram.messenger.beta); mismatches silently disable FCM. 5. Release keystore: TMessagesProj/config/release.keystore must exist; gradle will not error but signing fails at packaging stage. 6. C++ stdlib: Application.mk specifies stl=c++_shared; mixing with static stdlib in external libraries causes crashes.

• MTProto (Mobile Transport Protocol) — Telegram's custom binary protocol implemented across TgNetWrapper.cpp and JNI bindings; fundamental to understanding message serialization, encryption, and server communication in this codebase
• BoringSSL / TLS 1.2+ Handshake — Bundled in TMessagesProj/jni/boringssl/ and used for all encrypted transport; knowledge of AEAD ciphers (AES-GCM) and certificate validation required to understand message encryption
• Java Native Interface (JNI) — Critical bridge between Java UI (TMessagesProj/src/main/) and C++ crypto/networking (TMessagesProj/jni/); understanding JNI array marshaling and callback patterns is essential for modifying protocol layer
• Android NDK CMake Integration — TMessagesProj/jni/CMakeLists.txt orchestrates compilation of native code for multiple ABIs (armeabi-v7a, arm64-v8a, x86, x86_64); required to build and deploy message encryption layer
• SQLite via JNI (SqliteWrapper) — TMessagesProj/jni/SqliteWrapper.cpp wraps SQLite database for persistent message storage; understanding prepared statements and transaction isolation prevents data corruption in offline scenarios
• Android Manifest Variants (debug/release/SDK23+) — TMessagesProj/config/ splits permissions and entry points by build type; required to understand how Firebase messaging, camera access, and background services are conditionally enabled
• End-to-End Encryption (E2E) / Double Ratchet — Telegram's Secret Chats implement E2E key ratcheting in C++ layer (TgNetWrapper); understanding forward secrecy and key derivation is critical for auditing security-sensitive code

• TelegramMessenger/Telegram-iOS — Official Telegram iOS implementation; parallel codebase using same MTProto protocol, useful for understanding cross-platform messaging architecture
• tdlib/td — TDLib (Telegram Database Library) provides language-neutral MTProto client; reference for understanding protocol-layer abstractions without UI coupling
• google/boringssl — Upstream BoringSSL repository bundled in TMessagesProj/jni/boringssl/; critical for understanding crypto primitives and TLS implementation
• grpc-java/grpc-java — Java gRPC; relevant for understanding async RPC patterns similar to Telegram's MTProto framing in TgNetWrapper
• signalapp/Signal-Android — Open-source encrypted messaging app with similar JNI+crypto architecture; alternative reference for E2E messaging patterns

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add unit tests for JNI wrapper modules (NativeLoader, TgNetWrapper, SqliteWrapper)

The repo contains critical JNI bridge code in TMessagesProj/jni/ (NativeLoader.cpp, TgNetWrapper.cpp, SqliteWrapper.cpp) that handles native-to-Java interop for networking, database, and resource loading. These modules lack corresponding Android instrumented tests or JNI test fixtures. Adding tests would catch integration issues early and prevent regressions in native calls, which are difficult to debug.

• [ ] Create TMessagesProj/src/androidTest/java/org/telegram/messenger/NativeLoaderTest.java with JNI initialization tests
• [ ] Create TMessagesProj/src/androidTest/java/org/telegram/messenger/TgNetWrapperTest.java testing native network calls and callbacks
• [ ] Create TMessagesProj/src/androidTest/java/org/telegram/messenger/SqliteWrapperTest.java for database JNI binding verification
• [ ] Add CMake test configuration in TMessagesProj/jni/CMakeLists.txt for native unit tests
• [ ] Document JNI testing approach in a new docs/JNI_TESTING.md file with examples

Add GitHub Actions workflow for Android build verification and APK signing validation

The repo contains TMessagesProj/config/release/release.keystore and separate debug/release manifests, indicating multi-variant builds are essential. However, there's no CI workflow visible to verify that both debug and release builds complete successfully, that manifests are valid, and that signing works. This prevents contributor PRs from being validated before review, risking broken builds in main.

• [ ] Create .github/workflows/android-build.yml that runs './gradlew assembleDebug assembleRelease'
• [ ] Add validation step to verify TMessagesProj/config/debug/AndroidManifest.xml and release variants parse correctly using aapt
• [ ] Add step to verify boringssl CMake build succeeds (TMessagesProj/jni/boringssl/CMakeLists.txt compilation)
• [ ] Add Firebase config validation step for google-services.json
• [ ] Include build artifact upload for debug APK to workflow artifacts for manual testing by reviewers

Refactor and document boringssl CMake integration with clear build instructions

The repo includes a vendored boringssl library (TMessagesProj/jni/boringssl/) with custom CMake configuration (CMakeLists.txt, cmake/OpenSSLConfig.cmake, cmake/go.cmake, cmake/paths.cmake) but lacks documentation on how this integrates with the main NDK build, what Go tooling is required, or how to troubleshoot build failures. This creates friction for contributors modifying crypto code. Clear documentation and a dedicated build script would reduce setup time.

• [ ] Create docs/BORINGSSL_BUILD.md documenting boringssl build requirements (Go version, NDK version, ANDROID_NDK_HOME setup)
• [ ] Create TMessagesProj/jni/build_boringssl.sh script that clearly shows cmake invocation with all required flags
• [ ] Add comments to TMessagesProj/jni/CMakeLists.txt explaining boringssl target dependencies and include paths
• [ ] Document in docs/ why boringssl is vendored instead of using system OpenSSL, referencing security_guidelines from README
• [ ] Add troubleshooting section in docs/BORINGSSL_BUILD.md for common CMake/Go errors

• Add unit tests for TMessagesProj/jni/SqliteWrapper.cpp JNI bindings; currently no visible test coverage for database layer that handles message persistence
• Create gradle-level integration tests for BuildVars.java configuration injection; document required env vars (API_ID, API_HASH, MAPS_API_KEY) in a .env.example file to prevent silent failures on first clone
• Audit and document boringssl/ dependencies in TMessagesProj/jni/boringssl/CMakeLists.txt (currently 5+ Go build scripts and custom cmake modules); add comments linking to which crypto features depend on which submodules

• High · Outdated Dependency: Stripe Android SDK — TMessagesProj/build.gradle - dependencies section. The project uses stripe-android:2.0.2, which is significantly outdated (released in 2018). This version likely contains known security vulnerabilities. Current versions are in the 19.x+ range. Fix: Update to the latest stable version of stripe-android (currently 19.x or higher). Run 'gradle dependencyUpdates' to identify all outdated dependencies.
• High · Outdated Dependency: mp4parser — TMessagesProj/build.gradle - dependencies section. The isoparser library (mp4parser:1.0.6) from 2014 is severely outdated and likely contains unpatched security issues related to media file parsing. Fix: Replace with a maintained media parsing library or update if newer versions are available. Consider using ExoPlayer or MediaCodec for media handling.
• High · Release Keystore Stored in Repository — TMessagesProj/config/release.keystore. The file 'TMessagesProj/config/release.keystore' appears to be a signing keystore committed to the repository. This is a critical security issue as it could allow unauthorized APK signing if compromised. Fix: Immediately remove the keystore from version control history using 'git filter-branch' or 'BFG Repo-Cleaner'. Store keystores securely outside the repository, using environment variables or secure credential management systems.
• High · Firebase Configuration Exposed — TMessagesProj/google-services.json. The file 'TMessagesProj/google-services.json' contains Firebase configuration that may include API keys and project identifiers. If this contains sensitive credentials, it poses a security risk. Fix: Verify the contents of google-services.json. While some Firebase configs are safe to commit, ensure no sensitive keys are exposed. Consider using Gradle build variants to inject this at build time rather than committing it.
• Medium · Multiple Outdated Dependencies — TMessagesProj/build.gradle - dependencies section. Several dependencies have known vulnerabilities: play-services-cast-framework:21.4.0, firebase-messaging:22.0.0, firebase-config:21.0.1, and firebase-appindexing:20.0.0 are all outdated by multiple major versions. Fix: Run 'gradle dependencyUpdates' and update all dependencies to their latest stable versions. Test thoroughly after updates to ensure compatibility.
• Medium · Insecure HTTP Library - NanoHTTPD — TMessagesProj/build.gradle - dependencies section. The nanohttpd:2.3.1 library is from 2015 and is outdated. If used for any HTTPS operations, it may not support modern TLS versions or have security patches. Fix: Update to the latest version of nanohttpd or consider using OkHttp3 for HTTP client functionality. Verify TLS 1.2+ support if this handles sensitive data.
• Medium · Deprecated Firebase Libraries — TMessagesProj/build.gradle - dependencies section. firebase-appindexing:20.0.0 and several other Firebase libraries are deprecated or contain deprecated APIs. These versions may lack security updates. Fix: Update Firebase dependencies to their latest versions (currently 22+). Review Firebase documentation for any deprecated features being used.
• Medium · Missing Security Headers and Certificate Pinning — TMessagesProj/jni/TgNetWrapper.cpp and Java networking code. No evidence of certificate pinning or security header configuration visible. For a messaging app, this is a significant concern for protecting against MITM attacks. Fix: Implement certificate pinning for API communications. Use Network Security Configuration for Android to enforce TLS 1.2+ and restrict acceptable ciphers.
• Medium · BoringSSL Custom Build — TMessagesProj/jni/boringssl/. The project includes a custom build of BoringSSL. If not regularly updated with upstream security patches, this could lag behind current cryptographic best practices. Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.