How NagramXF is structured and why Telegram forks keep thriving

If you've ever looked at the source code of the official Telegram client for Android, you probably remember that feeling of slight bewilderment. A massive codebase TMessagesProj, a mix of Java and C++, tons of custom Views and homegrown interface rendering. Despite all the architectural complexity, an entire ecosystem of forks has grown around the Telegram client. Developers are constantly trying to rework the app to suit their needs: some add hidden read receipts, others remove ads or bolt on new themes.

Recently, I came across the NagramXF repository on GitHub. It's a fork of the popular Nagram X client, whose author decided not to limit themselves to a single branch and bundled features from several well-known projects under the hood: AyuGram, exteraGram, Cherrygram, and OctoGram.

Let's break down what this project is, how it's structured internally, and how to build your own APK from the source code.

A Frankenstein of the best third-party client features

The history of alternative Telegram clients for Android resembles a construction kit. First came the Nekogram fork, then Nagram, later Nagram X, and now we've arrived at NagramXF. The project author Keeperorowner had a simple goal: take the base stability of Nagram X and port useful improvements from other closed and open forks into it.

Here's what made it into the build:

• Features from AyuGram: saving the history of edited and deleted messages directly on the device, flexible configuration of the "typing" status, and hidden read receipts for conversations.
• Customization features from exteraGram and Cherrygram: fine-tuned fonts, icon styles, custom chat dividers, and an extended message forwarding menu without the author.
• Minor UI tweaks from OctoGram: quick link copying, simplified profile viewing, and animation optimization in lists.

An interesting detail: in the repository description, the author honestly warns that some features were obtained through reverse engineering of closed builds. The code retains references to the original authors of various patches, which for open-source forks of this kind is rather a pleasant rarity.

Under the hood and structural specifics

The repository is quite hefty, around 800 megabytes without submodules. Inside is a classic project TMessagesProj, but with notable changes to modules and helpers.

If you look into the package tw.nekomimi.nekogram.helpers, the lineage from Nekogram is immediately apparent. For example, remote management of metadata and client configuration is tied to the class BaseRemoteHelper, which reads parameters from a special service channel.

The fork's architecture rests on three pillars:

1. The base Telegram Android code, periodically pulled from upstream of the official repository DrKLO/Telegram.
2. An event interception layer: incoming messages are cached to a local SQLite database before the server sends a command to delete or edit them (this is how AyuGram's functionality works).
3. UI patches: an overlay on top of standard Telegram Activities and controllers, adding toggles to the settings menu.

How to build the project locally

Building Telegram forks has always been a separate quest, but NagramXF has a fairly straightforward guide. If you want to dig into the code or build a clean build with your own keys, you'll need Android Studio, a couple of keys from the Telegram developer console, and about 15 minutes of free time.

First, clone the repository along with all submodules:

git clone --recursive --shallow-submodules https://github.com/Keeperorowner/NagramXF.git NagramXF

If you forgot the --recursive flag during the initial clone, you can pull the submodules manually:

git submodule update --init --recursive --depth=1

Next, head to my.telegram.org, log in, and create a new application to get your TELEGRAM_APP_ID and TELEGRAM_APP_HASH. Without them, the client simply won't be able to authenticate with Telegram servers.

In the project root, create a local.properties file and add the credentials you received:

TELEGRAM_APP_ID=1234567
TELEGRAM_APP_HASH=0123456789abcdef0123456789abcdef

If you're building a release APK for regular use, you should also add your keystore parameters there:

KEYSTORE_PASS=your_keystore_password
ALIAS_NAME=your_alias_name
ALIAS_PASS=your_alias_password

Now you need to configure a couple of system parameters in the code:

• In TMessagesProj/src/main/AndroidManifest.xml, specify your Google Maps API key (if you want location sharing to work correctly).
• In the BaseRemoteHelper.java file, specify the metadata channel ID.
• Drop google-services.json into TMessagesProj/ if you need push notifications via Google FCM.

After that, the project opens in Android Studio and builds with the standard assembleRelease or assembleDebug task.

Who might find this project useful

Clients like NagramXF are interesting in two scenarios.

First, for Android developers. If you want to see how message interceptors, local storage, and patches on top of Telegram's massive legacy monolith are implemented in practice, NagramXF demonstrates this clearly. Here you can peek at the implementation of custom menus, network event overrides, and NDK usage.

Second, for those who find the base Telegram version too limited in settings. NagramXF combines features that previously required choosing between AyuGram and exteraGram. Everything is gathered in one place here.

Of course, you need to consider the risks: using third-party clients with closed patches requires trust in the fork author. But if you need a customizable client with an open build process, NagramXF looks like an interesting experiment.