# fossifyorg/messages architecture

> Architecture diagram of the GitHub repository fossifyorg/messages, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fossifyorg/messages
- Repository: https://github.com/fossifyorg/messages

## Overview

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: [`app/src/main/kotlin/org/fossify/messages/models/Message.kt`](https://github.com/fossifyorg/messages/blob/main/app/src/main/kotlin/org/fossify/messages/models/Message.kt) (Message models), [`app/src/main/kotlin/org/fossify/messages/activities/ThreadActivity.kt`](https://github.com/fossifyorg/messages/blob/main/app/src/main/kotlin/org/fossify/messages/activities/ThreadActivity.kt) (Thread), [`app/src/main/kotlin/org/fossify/messages/receivers/SmsReceiver.kt`](https://github.com/fossifyorg/messages/blob/main/app/src/main/kotlin/org/fossify/messages/receivers/SmsReceiver.kt) (Receivers), [`app/src/main/kotlin/org/fossify/messages/databases/MessagesDatabase.kt`](https://github.com/fossifyorg/messages/blob/main/app/src/main/kotlin/org/fossify/messages/databases/MessagesDatabase.kt) (Database)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["UI layer"]
  node_main_activity["Main<br/>activity<br/>[MainActivity.kt]"]
  node_thread_activity["Thread<br/>activity<br/>[ThreadActivity.kt]"]
  node_details_activity["Details<br/>activity"]
  node_settings_activity["Settings<br/>activity"]
  node_blocked_activity["Blocked keywords<br/>activity"]
  node_conversation_adapters["Conversation lists<br/>adapter set"]
  node_thread_adapter["Thread items<br/>adapter<br/>[ThreadAdapter.kt]"]
  node_attachment_adapters["Attachment views<br/>adapter set"]
  node_blocked_dialogs["Blocked dialogs<br/>dialog set"]
end

subgraph group_core["Core data"]
  node_app["App<br/>[App.kt]"]
  node_message_models[("Message models<br/>domain models<br/>[Message.kt]")]
  node_messages_db[("Database")]
  node_daos["DAOs<br/>persistence interfaces<br/>[MessagesDao.kt]"]
  node_messaging_cache(("Cache<br/>[MessagingCache.kt]"))
  node_cross_cutting["App helpers<br/>shared helpers<br/>[Config.kt]"]
end

subgraph group_messaging["Messaging boundary"]
  node_messaging_core["Messaging core<br/>sms/mms logic<br/>[Messaging.kt]"]
  node_sms_sender["SMS sender<br/>send pipeline<br/>[SmsSender.kt]"]
  node_receivers["Receivers<br/>[SmsReceiver.kt]"]
  node_headless_service["Headless send"]
end

subgraph group_io["Import/export"]
  node_attachment_helpers["Attachment tools<br/>attachment pipeline<br/>[AttachmentUtils.kt]"]
  node_import_export["Import/export<br/>backup pipeline"]
end

subgraph group_build["Build & release"]
  node_build_flavors["Build flavors<br/>gradle config<br/>[build.gradle.kts]"]
  node_release_tooling["Release tooling<br/>distribution"]
end

node_app -->|"starts"| node_main_activity
node_main_activity -->|"lists"| node_conversation_adapters
node_main_activity -->|"opens"| node_thread_activity
node_thread_activity -->|"renders"| node_thread_adapter
node_thread_activity -->|"send"| node_messaging_core
node_thread_activity -->|"shows"| node_attachment_adapters
node_details_activity -->|"uses"| node_message_models
node_settings_activity -->|"configures"| node_cross_cutting
node_blocked_activity -->|"manages"| node_blocked_dialogs
node_conversation_adapters -->|"binds"| node_message_models
node_thread_adapter -->|"binds"| node_message_models
node_attachment_adapters -->|"formats"| node_attachment_helpers
node_message_models -->|"persisted in"| node_messages_db
node_messages_db -->|"exposes"| node_daos
node_daos -->|"cached by"| node_messaging_cache
node_messaging_core -->|"delegates"| node_sms_sender
node_messaging_core -->|"observes callbacks"| node_receivers
node_receivers -->|"updates"| node_messages_db
node_receivers -->|"notifies"| node_cross_cutting
node_headless_service -->|"invokes"| node_sms_sender
node_import_export -->|"serializes"| node_message_models
node_import_export -->|"reads/writes"| node_messages_db
node_attachment_helpers -->|"attaches"| node_message_models
node_cross_cutting -->|"supports"| node_receivers
node_build_flavors -->|"ships via"| node_release_tooling

click node_app "https://github.com/fossifyorg/messages/blob/main/app/src/main/kotlin/org/fossify/messages/App.kt"
click node_main_activity "https://github.com/fossifyorg/messages/blob/main/app/src/main/kotlin/org/fossify/messages/activities/MainActivity.kt"
click node_thread_activity "https://github.com/fossifyorg/messages/blob/main/app/src/main/kotlin/org/fossify/messages/activities/ThreadActivity.kt"
click node_details_activity "https://github.com/fossifyorg/messages/blob/main/app/src/main/kotlin/org/fossify/messages/activities/ConversationDetailsActivity.kt"
click node_settings_activity "https://github.com/fossifyorg/messages/blob/main/app/src/main/kotlin/org/fossify/messages/activities/SettingsActivity.kt"
click node_blocked_activity "https://github.com/fossifyorg/messages/blob/main/app/src/main/kotlin/org/fossify/messages/activities/ManageBlockedKeywordsActivity.kt"
click node_conversation_adapters "https://github.com/fossifyorg/messages/blob/main/app/src/main/kotlin/org/fossify/messages/adapters/ConversationsAdapter.kt"
click node_thread_adapter "https://github.com/fossifyorg/messages/blob/main/app/src/main/kotlin/org/fossify/messages/adapters/ThreadAdapter.kt"
click node_attachment_adapters "https://github.com/fossifyorg/messages/blob/main/app/src/main/kotlin/org/fossify/messages/adapters/AttachmentsAdapter.kt"
click node_blocked_dialogs "https://github.com/fossifyorg/messages/blob/main/app/src/main/kotlin/org/fossify/messages/dialogs/AddBlockedKeywordDialog.kt"
click node_message_models "https://github.com/fossifyorg/messages/blob/main/app/src/main/kotlin/org/fossify/messages/models/Message.kt"
click node_messages_db "https://github.com/fossifyorg/messages/blob/main/app/src/main/kotlin/org/fossify/messages/databases/MessagesDatabase.kt"
click node_daos "https://github.com/fossifyorg/messages/blob/main/app/src/main/kotlin/org/fossify/messages/interfaces/MessagesDao.kt"
click node_messaging_core "https://github.com/fossifyorg/messages/blob/main/app/src/main/kotlin/org/fossify/messages/messaging/Messaging.kt"
click node_sms_sender "https://github.com/fossifyorg/messages/blob/main/app/src/main/kotlin/org/fossify/messages/messaging/SmsSender.kt"
click node_receivers "https://github.com/fossifyorg/messages/blob/main/app/src/main/kotlin/org/fossify/messages/receivers/SmsReceiver.kt"
click node_headless_service "https://github.com/fossifyorg/messages/blob/main/app/src/main/kotlin/org/fossify/messages/services/HeadlessSmsSendService.kt"
click node_messaging_cache "https://github.com/fossifyorg/messages/blob/main/app/src/main/kotlin/org/fossify/messages/helpers/MessagingCache.kt"
click node_attachment_helpers "https://github.com/fossifyorg/messages/blob/main/app/src/main/kotlin/org/fossify/messages/helpers/AttachmentUtils.kt"
click node_import_export "https://github.com/fossifyorg/messages/blob/main/app/src/main/kotlin/org/fossify/messages/helpers/MessagesImporter.kt"
click node_cross_cutting "https://github.com/fossifyorg/messages/blob/main/app/src/main/kotlin/org/fossify/messages/helpers/Config.kt"
click node_build_flavors "https://github.com/fossifyorg/messages/blob/main/app/build.gradle.kts"
click node_release_tooling "https://github.com/fossifyorg/messages/tree/main/fastlane/Fastfile"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main_activity,node_thread_activity,node_details_activity,node_settings_activity,node_blocked_activity,node_conversation_adapters,node_thread_adapter,node_attachment_adapters,node_blocked_dialogs toneBlue
class node_app,node_message_models,node_messages_db,node_daos,node_messaging_cache,node_cross_cutting toneAmber
class node_messaging_core,node_sms_sender,node_receivers,node_headless_service toneMint
class node_attachment_helpers,node_import_export toneRose
class node_build_flavors,node_release_tooling toneIndigo
```

## Components

### UI layer

Screens, dialogs, and list adapters for conversations, threads, settings, and attachments.

- [Main](https://github.com/fossifyorg/messages/blob/main/app/src/main/kotlin/org/fossify/messages/activities/MainActivity.kt): activity · Primary conversation list and app entry screen. · `app/src/main/kotlin/org/fossify/messages/activities/MainActivity.kt`
- [Thread](https://github.com/fossifyorg/messages/blob/main/app/src/main/kotlin/org/fossify/messages/activities/ThreadActivity.kt): activity · Per-conversation message timeline and compose surface. · `app/src/main/kotlin/org/fossify/messages/activities/ThreadActivity.kt`
- [Details](https://github.com/fossifyorg/messages/blob/main/app/src/main/kotlin/org/fossify/messages/activities/ConversationDetailsActivity.kt): activity · Conversation settings, metadata, and actions. · `app/src/main/kotlin/org/fossify/messages/activities/ConversationDetailsActivity.kt`
- [Settings](https://github.com/fossifyorg/messages/blob/main/app/src/main/kotlin/org/fossify/messages/activities/SettingsActivity.kt): activity · App preferences and global configuration. · `app/src/main/kotlin/org/fossify/messages/activities/SettingsActivity.kt`
- [Blocked keywords](https://github.com/fossifyorg/messages/blob/main/app/src/main/kotlin/org/fossify/messages/activities/ManageBlockedKeywordsActivity.kt): activity · Manage keyword-based blocking and filtering rules. · `app/src/main/kotlin/org/fossify/messages/activities/ManageBlockedKeywordsActivity.kt`
- [Conversation lists](https://github.com/fossifyorg/messages/blob/main/app/src/main/kotlin/org/fossify/messages/adapters/ConversationsAdapter.kt): adapter set · Conversation, archived, recycle-bin, and search list rendering. · `app/src/main/kotlin/org/fossify/messages/adapters/ConversationsAdapter.kt`
- [Thread items](https://github.com/fossifyorg/messages/blob/main/app/src/main/kotlin/org/fossify/messages/adapters/ThreadAdapter.kt): adapter · Renders messages, send states, and thread item variations. · `app/src/main/kotlin/org/fossify/messages/adapters/ThreadAdapter.kt`
- [Attachment views](https://github.com/fossifyorg/messages/blob/main/app/src/main/kotlin/org/fossify/messages/adapters/AttachmentsAdapter.kt): adapter set · Attachment, media, document, and vCard presentation. · `app/src/main/kotlin/org/fossify/messages/adapters/AttachmentsAdapter.kt`
- [Blocked dialogs](https://github.com/fossifyorg/messages/blob/main/app/src/main/kotlin/org/fossify/messages/dialogs/AddBlockedKeywordDialog.kt): dialog set · 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](https://github.com/fossifyorg/messages/blob/main/app/src/main/kotlin/org/fossify/messages/App.kt): Android app · Application bootstrap and top-level wiring. · `app/src/main/kotlin/org/fossify/messages/App.kt`
- [Message models](https://github.com/fossifyorg/messages/blob/main/app/src/main/kotlin/org/fossify/messages/models/Message.kt): domain models · Conversation, message, draft, attachment, backup, and search data contracts. · `app/src/main/kotlin/org/fossify/messages/models/Message.kt`
- [Database](https://github.com/fossifyorg/messages/blob/main/app/src/main/kotlin/org/fossify/messages/databases/MessagesDatabase.kt): room database · Local persistence boundary for conversations, messages, drafts, and attachments. · `app/src/main/kotlin/org/fossify/messages/databases/MessagesDatabase.kt`
- [DAOs](https://github.com/fossifyorg/messages/blob/main/app/src/main/kotlin/org/fossify/messages/interfaces/MessagesDao.kt): persistence interfaces · Conversation, message, draft, attachment, and join-query access contracts. · `app/src/main/kotlin/org/fossify/messages/interfaces/MessagesDao.kt`
- [Cache](https://github.com/fossifyorg/messages/blob/main/app/src/main/kotlin/org/fossify/messages/helpers/MessagingCache.kt): in-memory cache · Fast access layer above the database for conversation and message state. · `app/src/main/kotlin/org/fossify/messages/helpers/MessagingCache.kt`
- [App helpers](https://github.com/fossifyorg/messages/blob/main/app/src/main/kotlin/org/fossify/messages/helpers/Config.kt): shared 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](https://github.com/fossifyorg/messages/blob/main/app/src/main/kotlin/org/fossify/messages/messaging/Messaging.kt): sms/mms logic · High-level message sending and SMS/MMS utility orchestration. · `app/src/main/kotlin/org/fossify/messages/messaging/Messaging.kt`
- [SMS sender](https://github.com/fossifyorg/messages/blob/main/app/src/main/kotlin/org/fossify/messages/messaging/SmsSender.kt): send pipeline · Low-level SMS dispatch and manager integration. · `app/src/main/kotlin/org/fossify/messages/messaging/SmsSender.kt`
- [Receivers](https://github.com/fossifyorg/messages/blob/main/app/src/main/kotlin/org/fossify/messages/receivers/SmsReceiver.kt): broadcast receivers · Incoming SMS/MMS, sent/delivered callbacks, read/delete actions, and alarms. · `app/src/main/kotlin/org/fossify/messages/receivers/SmsReceiver.kt`
- [Headless send](https://github.com/fossifyorg/messages/blob/main/app/src/main/kotlin/org/fossify/messages/services/HeadlessSmsSendService.kt): service · 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](https://github.com/fossifyorg/messages/blob/main/app/src/main/kotlin/org/fossify/messages/helpers/AttachmentUtils.kt): attachment pipeline · Previewing, compression, parsing, and attachment utility helpers. · `app/src/main/kotlin/org/fossify/messages/helpers/AttachmentUtils.kt`
- [Import/export](https://github.com/fossifyorg/messages/blob/main/app/src/main/kotlin/org/fossify/messages/helpers/MessagesImporter.kt): backup pipeline · 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](https://github.com/fossifyorg/messages/blob/main/app/build.gradle.kts): gradle config · Foss, gplay, and debug build variants and packaging rules. · `app/build.gradle.kts`
- [Release tooling](https://github.com/fossifyorg/messages/tree/main/fastlane/Fastfile): distribution · Fastlane metadata, GitHub Actions, lint baselines, and release automation. · `fastlane/Fastfile`

## Connections

- 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.
