# itsluminous/clearsms architecture

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

- Interactive diagram: https://gitdiagram.com/itsluminous/clearsms
- Repository: https://github.com/itsluminous/clearsms

## Overview

Clear SMS is an offline Android SMS/MMS client that turns incoming carrier messages into categorized inbox items, financial records, reminders, OTP handling, and notifications, while supporting replies and user-managed rules. The graph follows the documented ingest-to-result workflow and retains finance, alerts, search, backups, diagnostics, and rule management as distinct product branches. Source evidence is partial: relationships are included only where shown by excerpts or the source index; unsampled implementations are represented by their exact tree directories where appropriate.

Main entry points: [`app/src/main/kotlin/app/clearsms/data/db/MessageDao.kt`](https://github.com/itsluminous/clearsms/blob/main/app/src/main/kotlin/app/clearsms/data/db/MessageDao.kt) (Message database), [`app/src/main/kotlin/app/clearsms/work/InitialSyncWorker.kt`](https://github.com/itsluminous/clearsms/blob/main/app/src/main/kotlin/app/clearsms/work/InitialSyncWorker.kt) (Catch-up import), [`app/src/main/kotlin/app/clearsms/data/rules/RuleEngine.kt`](https://github.com/itsluminous/clearsms/blob/main/app/src/main/kotlin/app/clearsms/data/rules/RuleEngine.kt) (Rule categorizer), [`app/src/main/kotlin/app/clearsms/data/repository/MessageRepository.kt`](https://github.com/itsluminous/clearsms/blob/main/app/src/main/kotlin/app/clearsms/data/repository/MessageRepository.kt) (Message repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App experience"]
  node_app_entry["App entry<br/>[MainActivity.kt]"]
  node_navigation["App navigation<br/>[ClearSmsApp.kt]"]
  node_inbox_ui["Inbox<br/>[InboxScreen.kt]"]
  node_conversation_ui["Conversation"]
  node_search_ui["Search<br/>[SearchScreen.kt]"]
  node_settings_ui["Settings<br/>[SettingsScreen.kt]"]
  node_rule_ui["Rule management<br/>[RulesScreen.kt]"]
end

subgraph group_message["Message processing"]
  node_categorizer["Rule categorizer<br/>[RuleEngine.kt]"]
end

subgraph group_data["Local data"]
  node_message_repo["Message repository"]
  node_message_store[("Message database<br/>[MessageDao.kt]")]
  node_settings_store[("Preferences")]
  node_backup["Backup and restore<br/>[BackupManager.kt]"]
end

subgraph group_insights["Finance and alerts"]
  node_finance_ui["Finance dashboard<br/>[FinanceScreen.kt]"]
  node_finance_data["Finance records"]
  node_alerts_ui["Bills and alerts<br/>[AlertsScreen.kt]"]
end

subgraph group_platform["Android integration"]
  node_sms_platform["SMS platform"]
  node_mms_platform["MMS platform"]
  node_initial_sync["Catch-up import"]
  node_notifications["Message notifications"]
  node_diagnostics["Diagnostics<br/>[Diag.kt]"]
end

node_user(("Phone user"))

node_user -->|"opens app"| node_app_entry
node_app_entry -->|"launches"| node_navigation
node_initial_sync -->|"imports SMS"| node_sms_platform
node_initial_sync -->|"imports MMS"| node_mms_platform
node_categorizer -->|"defines categories"| node_message_store
node_categorizer -.->|"returns results"| node_message_repo
node_message_repo -.->|"reads and writes"| node_message_store
node_message_store -.->|"provides messages"| node_inbox_ui
node_inbox_ui -.->|"opens thread"| node_conversation_ui
node_search_ui -.->|"searches messages"| node_message_repo
node_user -.->|"sends messages"| node_sms_platform
node_user -.->|"sends attachments"| node_mms_platform
node_message_store -.->|"routes incoming"| node_notifications
node_user -->|"views finances"| node_finance_ui
node_finance_ui -.->|"loads records"| node_finance_data
node_user -->|"views alerts"| node_alerts_ui
node_user -->|"manages rules"| node_rule_ui
node_rule_ui -.->|"configures rules"| node_categorizer
node_settings_ui -.->|"updates preferences"| node_settings_store
node_user -.->|"backs up data"| node_backup
node_initial_sync -->|"notifies imports"| node_notifications

click node_app_entry "https://github.com/itsluminous/clearsms/blob/main/app/src/main/kotlin/app/clearsms/MainActivity.kt"
click node_navigation "https://github.com/itsluminous/clearsms/blob/main/app/src/main/kotlin/app/clearsms/ui/navigation/ClearSmsApp.kt"
click node_inbox_ui "https://github.com/itsluminous/clearsms/blob/main/app/src/main/kotlin/app/clearsms/ui/inbox/InboxScreen.kt"
click node_conversation_ui "https://github.com/itsluminous/clearsms/blob/main/app/src/main/kotlin/app/clearsms/ui/conversation/ConversationScreen.kt"
click node_search_ui "https://github.com/itsluminous/clearsms/blob/main/app/src/main/kotlin/app/clearsms/ui/search/SearchScreen.kt"
click node_settings_ui "https://github.com/itsluminous/clearsms/blob/main/app/src/main/kotlin/app/clearsms/ui/settings/SettingsScreen.kt"
click node_sms_platform "https://github.com/itsluminous/clearsms/tree/main/app/src/main/kotlin/app/clearsms/sms"
click node_mms_platform "https://github.com/itsluminous/clearsms/tree/main/app/src/main/kotlin/app/clearsms/mms"
click node_initial_sync "https://github.com/itsluminous/clearsms/blob/main/app/src/main/kotlin/app/clearsms/work/InitialSyncWorker.kt"
click node_categorizer "https://github.com/itsluminous/clearsms/blob/main/app/src/main/kotlin/app/clearsms/data/rules/RuleEngine.kt"
click node_message_repo "https://github.com/itsluminous/clearsms/blob/main/app/src/main/kotlin/app/clearsms/data/repository/MessageRepository.kt"
click node_message_store "https://github.com/itsluminous/clearsms/blob/main/app/src/main/kotlin/app/clearsms/data/db/MessageDao.kt"
click node_settings_store "https://github.com/itsluminous/clearsms/blob/main/app/src/main/kotlin/app/clearsms/data/prefs/SettingsRepositoryImpl.kt"
click node_rule_ui "https://github.com/itsluminous/clearsms/blob/main/app/src/main/kotlin/app/clearsms/ui/rules/RulesScreen.kt"
click node_finance_ui "https://github.com/itsluminous/clearsms/blob/main/app/src/main/kotlin/app/clearsms/ui/finance/FinanceScreen.kt"
click node_finance_data "https://github.com/itsluminous/clearsms/blob/main/app/src/main/kotlin/app/clearsms/data/repository/FinanceRepository.kt"
click node_alerts_ui "https://github.com/itsluminous/clearsms/blob/main/app/src/main/kotlin/app/clearsms/ui/alerts/AlertsScreen.kt"
click node_notifications "https://github.com/itsluminous/clearsms/blob/main/app/src/main/kotlin/app/clearsms/notification/IncomingMessageRouter.kt"
click node_backup "https://github.com/itsluminous/clearsms/blob/main/app/src/main/kotlin/app/clearsms/data/backup/BackupManager.kt"
click node_diagnostics "https://github.com/itsluminous/clearsms/blob/main/app/src/main/kotlin/app/clearsms/diagnostics/Diag.kt"

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_app_entry,node_navigation,node_inbox_ui,node_conversation_ui,node_search_ui,node_settings_ui,node_rule_ui,node_user toneBlue
class node_categorizer toneAmber
class node_message_repo,node_message_store,node_settings_store,node_backup toneMint
class node_finance_ui,node_finance_data,node_alerts_ui toneRose
class node_sms_platform,node_mms_platform,node_initial_sync,node_notifications,node_diagnostics toneIndigo
```

## Components

### App experience

- [App entry](https://github.com/itsluminous/clearsms/blob/main/app/src/main/kotlin/app/clearsms/MainActivity.kt): `app/src/main/kotlin/app/clearsms/MainActivity.kt`
- [App navigation](https://github.com/itsluminous/clearsms/blob/main/app/src/main/kotlin/app/clearsms/ui/navigation/ClearSmsApp.kt): `app/src/main/kotlin/app/clearsms/ui/navigation/ClearSmsApp.kt`
- [Inbox](https://github.com/itsluminous/clearsms/blob/main/app/src/main/kotlin/app/clearsms/ui/inbox/InboxScreen.kt): `app/src/main/kotlin/app/clearsms/ui/inbox/InboxScreen.kt`
- [Conversation](https://github.com/itsluminous/clearsms/blob/main/app/src/main/kotlin/app/clearsms/ui/conversation/ConversationScreen.kt): `app/src/main/kotlin/app/clearsms/ui/conversation/ConversationScreen.kt`
- [Search](https://github.com/itsluminous/clearsms/blob/main/app/src/main/kotlin/app/clearsms/ui/search/SearchScreen.kt): `app/src/main/kotlin/app/clearsms/ui/search/SearchScreen.kt`
- [Settings](https://github.com/itsluminous/clearsms/blob/main/app/src/main/kotlin/app/clearsms/ui/settings/SettingsScreen.kt): `app/src/main/kotlin/app/clearsms/ui/settings/SettingsScreen.kt`
- [Rule management](https://github.com/itsluminous/clearsms/blob/main/app/src/main/kotlin/app/clearsms/ui/rules/RulesScreen.kt): `app/src/main/kotlin/app/clearsms/ui/rules/RulesScreen.kt`

### Message processing

- [Rule categorizer](https://github.com/itsluminous/clearsms/blob/main/app/src/main/kotlin/app/clearsms/data/rules/RuleEngine.kt): `app/src/main/kotlin/app/clearsms/data/rules/RuleEngine.kt`

### Local data

- [Message repository](https://github.com/itsluminous/clearsms/blob/main/app/src/main/kotlin/app/clearsms/data/repository/MessageRepository.kt): `app/src/main/kotlin/app/clearsms/data/repository/MessageRepository.kt`
- [Message database](https://github.com/itsluminous/clearsms/blob/main/app/src/main/kotlin/app/clearsms/data/db/MessageDao.kt): `app/src/main/kotlin/app/clearsms/data/db/MessageDao.kt`
- [Preferences](https://github.com/itsluminous/clearsms/blob/main/app/src/main/kotlin/app/clearsms/data/prefs/SettingsRepositoryImpl.kt): `app/src/main/kotlin/app/clearsms/data/prefs/SettingsRepositoryImpl.kt`
- [Backup and restore](https://github.com/itsluminous/clearsms/blob/main/app/src/main/kotlin/app/clearsms/data/backup/BackupManager.kt): `app/src/main/kotlin/app/clearsms/data/backup/BackupManager.kt`

### Finance and alerts

- [Finance dashboard](https://github.com/itsluminous/clearsms/blob/main/app/src/main/kotlin/app/clearsms/ui/finance/FinanceScreen.kt): `app/src/main/kotlin/app/clearsms/ui/finance/FinanceScreen.kt`
- [Finance records](https://github.com/itsluminous/clearsms/blob/main/app/src/main/kotlin/app/clearsms/data/repository/FinanceRepository.kt): `app/src/main/kotlin/app/clearsms/data/repository/FinanceRepository.kt`
- [Bills and alerts](https://github.com/itsluminous/clearsms/blob/main/app/src/main/kotlin/app/clearsms/ui/alerts/AlertsScreen.kt): `app/src/main/kotlin/app/clearsms/ui/alerts/AlertsScreen.kt`

### Android integration

- [SMS platform](https://github.com/itsluminous/clearsms/tree/main/app/src/main/kotlin/app/clearsms/sms): `app/src/main/kotlin/app/clearsms/sms`
- [MMS platform](https://github.com/itsluminous/clearsms/tree/main/app/src/main/kotlin/app/clearsms/mms): `app/src/main/kotlin/app/clearsms/mms`
- [Catch-up import](https://github.com/itsluminous/clearsms/blob/main/app/src/main/kotlin/app/clearsms/work/InitialSyncWorker.kt): `app/src/main/kotlin/app/clearsms/work/InitialSyncWorker.kt`
- [Message notifications](https://github.com/itsluminous/clearsms/blob/main/app/src/main/kotlin/app/clearsms/notification/IncomingMessageRouter.kt): `app/src/main/kotlin/app/clearsms/notification/IncomingMessageRouter.kt`
- [Diagnostics](https://github.com/itsluminous/clearsms/blob/main/app/src/main/kotlin/app/clearsms/diagnostics/Diag.kt): `app/src/main/kotlin/app/clearsms/diagnostics/Diag.kt`

### Other components

- **Phone user**

## Connections

- Phone user → App entry: opens app
- App entry → App navigation: launches (evidence: `app/src/main/kotlin/app/clearsms/MainActivity.kt`)
- Catch-up import → SMS platform: imports SMS (evidence: `app/src/main/kotlin/app/clearsms/work/InitialSyncWorker.kt`)
- Catch-up import → MMS platform: imports MMS (evidence: `app/src/main/kotlin/app/clearsms/work/InitialSyncWorker.kt`)
- Rule categorizer → Message database: defines categories
- Rule categorizer → Message repository: returns results
- Message repository → Message database: reads and writes
- Message database → Inbox: provides messages
- Inbox → Conversation: opens thread
- Search → Message repository: searches messages
- Phone user → SMS platform: sends messages
- Phone user → MMS platform: sends attachments
- Message database → Message notifications: routes incoming
- Phone user → Finance dashboard: views finances
- Finance dashboard → Finance records: loads records
- Phone user → Bills and alerts: views alerts
- Phone user → Rule management: manages rules
- Rule management → Rule categorizer: configures rules
- Settings → Preferences: updates preferences
- Phone user → Backup and restore: backs up data
- Catch-up import → Message notifications: notifies imports (evidence: `app/src/main/kotlin/app/clearsms/work/InitialSyncWorker.kt`)
