How fossifyorg/messages works
1. What this repo is
Fossify Messages is a self-contained Android messaging app focused on SMS/MMS. It is written in Kotlin and built as a single app module, with product flavors for foss, gplay, and debug. The app is designed to work offline and relies primarily on Android system messaging APIs and local storage rather than any backend service.
2. Top-level architecture
The codebase is organized in a classic Android layered shape: Activities/Dialogs/Adapters for UI, helpers/messaging/models for app logic and domain objects, database/DAO interfaces for persistence, and broadcast receivers/services for platform integration and background message handling.
3. User interface layer
The main screens are implemented as Activities such as MainActivity, ThreadActivity, NewConversationActivity, ConversationDetailsActivity, SettingsActivity, ArchivedConversationsActivity, and RecycleBinConversationsActivity. UI composition is largely XML-based (res/layout, res/menu, res/drawable) with RecyclerView adapters for conversation lists, threads, attachments, contacts, search results, and vCard viewing.
4. Conversation and message domain
The models package contains the app’s core business objects: Conversation, Message, Draft, Attachment, SIMCard, ScheduledMessage, backup/export/import models, and thread-item wrappers. These models are the shared data contract between UI, storage, import/export, and messaging flows.
5. Persistence boundary
MessagesDatabase and the DAO interfaces (MessagesDao, ConversationsDao, DraftsDao, AttachmentsDao, MessageAttachmentsDao) define the local persistence boundary. This is where conversations, messages, drafts, and attachment metadata are stored and queried. MessagingCache sits above the database as an in-memory optimization layer.
6. Sending and receiving messages
The messaging package wraps Android SMS/MMS functionality with SmsManager, SmsSender, Messaging, and utility classes. Outbound messages flow from the compose UI into this layer, then back through system callbacks handled by receivers such as SmsStatusSentReceiver, SmsStatusDeliveredReceiver, MmsSentReceiver, and SendStatusReceiver.
7. System and background integration
The app reacts to incoming system events through a broad set of receivers: SmsReceiver, MmsReceiver, DirectReplyReceiver, MarkAsReadReceiver, DeleteSmsReceiver, ScheduledMessageReceiver, and RescheduleAlarmsReceiver. There is also a HeadlessSmsSendService for background sending. This is the key boundary between the app and the Android telephony/notification framework.
8. Attachments and rich media
Attachment handling is a major subsystem. AttachmentUtils, AttachmentPreviews, ImageCompressor, and VCardParser support media, documents, and contact cards. Dedicated adapters and layout items exist for document, image, video, audio, and vCard rendering, which indicates that MMS content is first-class in the app’s data flow.
9. Import/export and backup
The app includes explicit backup/restore flows through MessagesImporter, MessagesReader, MessagesWriter, and dialogs for importing/exporting messages. There is a parallel import/export path for blocked keywords via BlockedKeywordsImporter and BlockedKeywordsExporter. The backup-related models (MessagesBackup, SmsBackup, MmsBackup, ExportedMessage, ImportResult) show that portability is a core feature, not an afterthought.
10. Blocking and filtering
Message filtering is handled as a distinct feature area with ManageBlockedKeywordsActivity, keyword dialogs, and receiver/parser utilities. The repository supports both blocking specific senders and filtering based on message content/keywords, with UI and persistence around that feature set.
11. Notifications, shortcuts, and app-level helpers
NotificationHelper, ShortcutHelper, ReceiverUtils, Config, Constants, and many extension files provide cross-cutting support for notifications, launcher shortcuts, formatting, and Android convenience APIs. This layer is where app-wide policies like lock-screen privacy or notification presentation are likely centralized.
12. Build, release, and distribution
The project is heavily automated with Gradle, Detekt/Lint baselines, GitHub Actions workflows, and Fastlane metadata for Play Store and F-Droid style distribution. The presence of gplay and foss flavors suggests feature or dependency differences between store builds, while fastlane/metadata and screenshots indicate release-management tooling rather than runtime architecture.
13. How data flows through the app
Typical flow is: system message event or compose action -> messaging/receiver layer -> database/models/cache -> UI adapters and activities. Secondary flows include import/export to files, blocking configuration updates, and scheduled messages routed through alarms/receivers. This makes the app predominantly event-driven, with the Android platform as the main external boundary.
Main entry points: Message.kt Message models · ThreadActivity.kt Thread · SmsReceiver.kt Receivers · MessagesDatabase.kt Database
Components 23
UI layer
Screens, dialogs, and list adapters for conversations, threads, settings, and attachments.
- Main · Primary conversation list and app entry screen.
app/src/main/kotlin/org/fossify/messages/activities/MainActivity.kt - Thread · Per-conversation message timeline and compose surface.
app/src/main/kotlin/org/fossify/messages/activities/ThreadActivity.kt - Details · Conversation settings, metadata, and actions.
app/src/main/kotlin/org/fossify/messages/activities/ConversationDetailsActivity.kt - Settings · App preferences and global configuration.
app/src/main/kotlin/org/fossify/messages/activities/SettingsActivity.kt - Blocked keywords · Manage keyword-based blocking and filtering rules.
app/src/main/kotlin/org/fossify/messages/activities/ManageBlockedKeywordsActivity.kt - Conversation lists · Conversation, archived, recycle-bin, and search list rendering.
app/src/main/kotlin/org/fossify/messages/adapters/ConversationsAdapter.kt - Thread items · Renders messages, send states, and thread item variations.
app/src/main/kotlin/org/fossify/messages/adapters/ThreadAdapter.kt - Attachment views · Attachment, media, document, and vCard presentation.
app/src/main/kotlin/org/fossify/messages/adapters/AttachmentsAdapter.kt - Blocked dialogs · Keyword add, export, and editing dialogs for blocking features.
app/src/main/kotlin/org/fossify/messages/dialogs/AddBlockedKeywordDialog.kt
Core data
Domain models, local storage, and cache used across the app.
- App · Application bootstrap and top-level wiring.
app/src/main/kotlin/org/fossify/messages/App.kt - Message models · Conversation, message, draft, attachment, backup, and search data contracts.
app/src/main/kotlin/org/fossify/messages/models/Message.kt - Database · Local persistence boundary for conversations, messages, drafts, and attachments.
app/src/main/kotlin/org/fossify/messages/databases/MessagesDatabase.kt - DAOs · Conversation, message, draft, attachment, and join-query access contracts.
app/src/main/kotlin/org/fossify/messages/interfaces/MessagesDao.kt - Cache · Fast access layer above the database for conversation and message state.
app/src/main/kotlin/org/fossify/messages/helpers/MessagingCache.kt - App helpers · Notifications, shortcuts, receiver utilities, constants, and config.
app/src/main/kotlin/org/fossify/messages/helpers/Config.kt
Messaging boundary
Outbound sending and Android telephony callbacks for SMS/MMS and scheduled delivery.
- Messaging core · High-level message sending and SMS/MMS utility orchestration.
app/src/main/kotlin/org/fossify/messages/messaging/Messaging.kt - SMS sender · Low-level SMS dispatch and manager integration.
app/src/main/kotlin/org/fossify/messages/messaging/SmsSender.kt - Receivers · Incoming SMS/MMS, sent/delivered callbacks, read/delete actions, and alarms.
app/src/main/kotlin/org/fossify/messages/receivers/SmsReceiver.kt - Headless send · Background SMS sending without foreground UI.
app/src/main/kotlin/org/fossify/messages/services/HeadlessSmsSendService.kt
Import/export
File-based portability, backups, blocked-keyword transfer, and rich attachment handling.
- Attachment tools · Previewing, compression, parsing, and attachment utility helpers.
app/src/main/kotlin/org/fossify/messages/helpers/AttachmentUtils.kt - Import/export · Message and blocked-keyword import/export plus backup readers and writers.
app/src/main/kotlin/org/fossify/messages/helpers/MessagesImporter.kt
Build & release
Gradle flavors, quality gates, and release/distribution tooling.
- Build flavors · Foss, gplay, and debug build variants and packaging rules.
app/build.gradle.kts - Release tooling · Fastlane metadata, GitHub Actions, lint baselines, and release automation.
fastlane/Fastfile
Connections 25
- App → Main: starts · Application launches into the main conversation UI.
- Main → Conversation lists: lists · Conversation screens render via RecyclerView adapters.
- Main → Thread: opens · Selecting a conversation navigates to the thread view.
- Thread → Thread items: renders · Thread UI uses message item adapters.
- Thread → Messaging core: send · Compose actions enter the messaging pipeline.
- Thread → Attachment views: shows · Thread view includes attachment presentation.
- Details → Message models: uses · Conversation metadata and actions operate on shared models.
- Settings → App helpers: configures · Settings update app-wide helpers and preferences.
- Blocked keywords → Blocked dialogs: manages · Blocked keyword flows are centered on dialogs.
- Conversation lists → Message models: binds · Conversation lists are driven by core domain objects.
- Thread items → Message models: binds · Thread rows are populated from message and thread item models.
- Attachment views → Attachment tools: formats · Attachment UI depends on preview and parsing utilities.
- Message models → Database: persisted in · Models are stored through the local database boundary.
- Database → DAOs: exposes · Database operations are defined by DAO interfaces.
- DAOs → Cache: cached by · Cache sits above persistence for faster reads.
- Messaging core → SMS sender: delegates · Higher-level send logic delegates to the sender layer.
- Messaging core → Receivers: observes callbacks · Send status and inbound events return through receivers.
- Receivers → Database: updates · Incoming and status events update local message state.
- Receivers → App helpers: notifies · Receivers use app-level notification and utility helpers.
- Headless send → SMS sender: invokes · Background sending runs through the same send path.
- Import/export → Message models: serializes · Import/export and backup flows work from shared models.
- Import/export → Database: reads/writes · File-based import and export move data through storage.
- Attachment tools → Message models: attaches · Attachment parsing and compression feed message data.
- App helpers → Receivers: supports · Utility helpers coordinate system event handling.
- Build flavors → Release tooling: ships via · Build variants are packaged and published through release automation.