Introducing a new way to review your PRs.

Read the announcement

ayugram / ayugram4a

Just an exteraGram based client with ToS breaking features in mind.

View on GitHub

13 documents · Updated Nov 19, 2026

docs / ayugram-custom-features

Ayugram Custom Features

Overview

This doc owns TMessagesProj/src/main/java/com/radolyn/ayugram/** and the AyuGram string resources in TMessagesProj/…/ayu.xml. The package is a set of AyuGram-specific hooks and UI surfaces layered onto Telegram's controllers, storage, networking, and message cells. Most runtime entry points are static helpers that patched Telegram code can call: AyuConfig.java for feature flags, AyuMessagesController.java for deleted/edit-history persistence, AyuForwarder.java and easy/AyuEasyUtils.java for forwarding/resending restricted messages, sync/AyuSyncController.java for device sync, and utils/AyuGhostUtils.java/utils/AyuState.java for ghost-mode read-state routing.

Configuration is global, process-local state loaded from the ayuconfig SharedPreferences file in AyuConfig.java. loadConfig() initializes booleans for ghost mode, message saving, regex filtering, drawer buttons, AyuSync, and WAL mode; the preference screens mutate the same static fields and immediately persist via AyuConfig.editor. String-valued settings such as deletedMarkText, editedMarkText, syncServerURL, syncServerToken, and regexFilters are read lazily from preferences. Regex filters are stored as a JSON array string and compiled/cached by AyuFilter.java, with RegexFilterEditActivity.java validating new patterns before AyuConfig.addFilter() or editFilter() rebuilds the cache.

The main settings surface is ui/…/AyuGramPreferencesActivity.java, backed by strings in values*/ayu.xml. It exposes ghost essentials, deleted/edit history, message-saving preferences, QoL toggles, customization text, AyuSync status, and debug database actions. Subscreens include MessageSavingPreferencesActivity.java for media/formatting/reaction/bot save policy, RegexFiltersPreferencesActivity.java plus RegexFilterPopup.java/RegexFilterEditActivity.java for filter management, and AyuSyncPreferencesActivity.java for server URL, token, secure transport, profile, force-sync, and sync diagnostics. ui/…/AyuUi.java centralizes edit dialogs that persist string settings.

Message history state is stored in a Room database named ayu-data. database/AyuDatabase.java defines version 21 with EditedMessage, DeletedMessage, and DeletedMessageReaction; database/AyuData.java builds it with allowMainThreadQueries() and fallbackToDestructiveMigration(). database/…/AyuMessageBase.java is the shared persistence schema for user/dialog/topic/message identity, forwarding/reply metadata, text, serialized entities, media paths, thumbs, document type, document serialization, attributes, and MIME type. EditedMessageDao.java retrieves revisions and sync pages; DeletedMessageDao.java retrieves individual/ranged/grouped deleted messages, inserts deletion rows/reactions, checks existence, and deletes rows.

messages/AyuMessagesController.java is the persistence facade. It writes copied media under Downloads/AyuGram/Saved Attachments, uses the proprietary mapper com.radolyn.ayugram.proprietary.AyuMessageUtils to map Telegram TLRPC.Message data into AyuMessageBase rows and back, and posts AyuConstants.MESSAGE_EDITED_NOTIFICATION after edit revisions are inserted. It skips saving when AyuConfig.saveEditedMessageFor() or saveDeletedMessageFor() says the feature is disabled or the dialog is a bot excluded by saveForBots. Deleted messages are deduplicated by (userId, dialogId, topicId, messageId) and can carry persisted reactions when saveReactions is enabled. ui/AyuMessageHistory.java renders edit revisions by reconstructing TLRPC.TL_message objects through the proprietary mapper, and ui/AyuMessageCell.java opens saved media or copies saved text.

Ghost-mode and read-state behavior is split between persistent flags and short-lived allowances. AyuConfig.setGhostMode() flips packet-sending flags, while utils/AyuState.java holds one-shot counters for allowing read packets, marking automatically scheduled sends, hiding selection, and permitting local deletions. utils/AyuGhostUtils.java routes read requests: markReadOnServer() builds either TL_channels_readHistory or TL_messages_readHistory, temporarily allows one read packet, and processes affected-message PTS; markReadLocally() updates MessagesController.dialogs_read_inbox_max and MessagesStorage without a server packet. It also converts InputPeer/InputChannel into Telegram dialog IDs and extracts dialog/message IDs from read-history request objects.

Forwarding and synchronous send helpers exist to preserve deleted or no-forward messages by re-uploading content instead of using Telegram forwarding. AyuForwarder.java detects messages flagged messageOwner.ayuDeleted, messageOwner.ayuNoforwards, or chats marked ayuNoforwards, batches normal versus Ayu-forward messages, downloads needed media through AyuEasyUtils.loadDocumentsSync(), and sends text/documents/photos with generated group IDs for albums. easy/AyuEasyUtils.java wraps SendMessagesHelper and FileLoader calls in blocking helpers. Its EasyWaiter subclasses subscribe to NotificationCenter file/message events and wait on a CountDownLatch until send/upload/download completion or failure notification.

AyuSync is an optional WebSocket/HTTP sync layer. sync/AyuSyncConfig.java constructs HTTP and WebSocket URLs from AyuConfig.getSyncServerURL() and useSecureConnection, and sync/AyuInterceptor.java adds X-APP-PACKAGE plus Authorization headers to HTTP calls. sync/AyuSyncController.java runs on a dedicated DispatchQueue, loads activated Telegram accounts from UserConfig, verifies a token by calling /user/v1, requires AyuUser.isMVP, registers the device at /sync/register/v1 with AyuUtils.getDeviceName() and getDeviceIdentifier(), then creates AyuSyncWebSocketClient.java. The WebSocket sends the package, device identifier, and token headers, records last-sent/received timestamps in AyuSyncState.java, and dispatches JSON events back to AyuSyncController.invokeHandler(). Current handled sync payloads are sync_force, sync_batch, and sync_read from sync/models/*; force sync emits current dialog read states, while incoming sync_read applies local read state through AyuGhostUtils.markReadLocally().

Path-routing notes: AyuGram-owned Java lives under com.radolyn.ayugram, but several entry points are meant to be called by patched Telegram classes outside this ownership boundary. Static notification IDs and drawer/menu option IDs are centralized in AyuConstants.java; if an external caller routes on those constants, it should not duplicate raw numbers. Localized AyuGram UI strings are isolated in each values*/ayu.xml, so adding a preference row in ui/preferences/* should add the base key in values/ayu.xml and update translations as needed. messages/AyuMessagesController.java and ui/AyuMessageHistory.java depend on the proprietary AyuMessageUtils package even though that package is not present under the covered source tree; that mapper is the path between Telegram TLRPC objects and AyuGram database rows.

Coupling

  • If database/…/AyuMessageBase.java changes, update both sides of com.radolyn.ayugram.proprietary.AyuMessageUtils: messages/AyuMessagesController.java writes rows through it, and ui/AyuMessageHistory.java reconstructs TLRPC.Message objects through it. A schema-only change can otherwise save rows that the history UI cannot render.
  • If AyuConstants.DOCUMENT_TYPE_* or media fields in AyuMessageBase.java change, verify AyuMessagesController.java, AyuMessageHistory.java, and AyuMessageCell.java; the UI decides whether to reuse Telegram cached media or open saved media paths from those fields.
  • If AyuSync JSON models in sync/…/*.java change, update AyuSyncController.invokeHandler() and the server contract together. The controller switches on literal strings (sync_force, sync_batch, sync_read) and deserializes raw JsonObject/Gson payloads without a schema migration layer.
  • If ghost/read behavior is changed, verify both utils/AyuGhostUtils.java and utils/AyuState.java. markReadOnServer() intentionally sets a one-shot read-packet allowance before sending Telegram read-history requests, while markReadLocally() mutates MessagesController and MessagesStorage without network traffic.
  • If forwarding behavior changes in AyuForwarder.java, verify the blocking send/download waiters in easy/*. Album forwarding relies on AyuEasyUtils.createParams() group IDs and waits only for the final item in grouped sends.
  • If a preference key is renamed in AyuConfig.java, update all preference screens that persist it (ui/preferences/*) and any default reads. The module uses raw string keys rather than generated constants.
  • If values/ayu.xml adds or renames an Ayu string, update the locale-specific values-*/ayu.xml files because the AyuGram preference and message-history UI use LocaleController.getString(R.string.*) directly.

Risks

  • database/AyuData.java builds the Room database with fallbackToDestructiveMigration(), and AyuDatabase.java is already at version 21. If the schema changes without an explicit migration, existing deleted-message and edit-history rows can be silently wiped on upgrade.
  • database/AyuData.java uses allowMainThreadQueries(), and messages/AyuMessagesController.java performs inserts, existence checks, deletes, and media file deletion synchronously. Large histories or slow storage can block UI paths that call these facades.
  • ui/…/AyuGramPreferencesActivity.java saves the WAL toggle under "WALMode", but AyuConfig.java loads "walMode". Changing or relying on this toggle can appear ineffective because the saved key and loaded key do not match.
  • easy/EasyWaiter.java waits indefinitely on a CountDownLatch; DummyMessageWaiter.java, DummyFileLoadWaiter.java, and DummyFileUploadWaiter.java only release when matching NotificationCenter events arrive. If Telegram changes notification names, argument shapes, or matching file-path formats, AyuForwarder.java can hang while re-sending restricted messages.
  • sync/AyuSyncController.java assumes accounts.get(req.userId) returns an account after accountExists() and then calls MessagesController.getInstance(accountId). If a sync_batch event contains mixed or malformed nested userId values, a null account mapping can break sync handling before later events are processed.