# dilithegit/mahari architecture

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

- Interactive diagram: https://gitdiagram.com/dilithegit/mahari
- Repository: https://github.com/dilithegit/mahari

## Overview

Mahari is an offline-first Android M-Pesa finance app: SMS capture and backfill feed parsed, categorized transactions into local storage, which power dashboard, budget, search, and recap features. Sharing and privacy controls complement the core workflow; opt-in cloud sync sends structured transactions to a FastAPI service for encrypted storage and ML insights. The Android implementation was not excerpted, so its relationships below rely on README statements; backend call relationships are directly visible in the sampled backend source.

Main entry points: [`app/src/main/java/com/example/mahari/ui/dashboard/DashboardViewModel.kt`](https://github.com/dilithegit/mahari/blob/main/app/src/main/java/com/example/mahari/ui/dashboard/DashboardViewModel.kt) (Dashboard calculations), [`mahari_backend/main.py`](https://github.com/dilithegit/mahari/blob/main/mahari_backend/main.py) (Sync API), [`app/src/main/java/com/example/mahari/data/recap/RecapMlEngine.kt`](https://github.com/dilithegit/mahari/blob/main/app/src/main/java/com/example/mahari/data/recap/RecapMlEngine.kt) (On-device recap), [`app/src/main/java/com/example/mahari/data/parser/MpesaParser.kt`](https://github.com/dilithegit/mahari/blob/main/app/src/main/java/com/example/mahari/data/parser/MpesaParser.kt) (M-Pesa parser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Transaction Capture"]
  node_receiver["SMS receiver<br/>[SmsReceiver.kt]"]
  node_backfill["SMS backfill"]
  node_parser["M-Pesa parser<br/>[MpesaParser.kt]"]
  node_categorizer["Transaction categorizer<br/>[Categorizer.kt]"]
end

subgraph group_local["Local Finance Data"]
  node_repository["Transaction repository"]
  node_database[("Room database<br/>[MahariDatabase.kt]")]
end

subgraph group_insights["Financial Insights"]
  node_budget["Budget engine<br/>[BudgetEngine.kt]"]
  node_recap["On-device recap<br/>[RecapMlEngine.kt]"]
  node_stats["Statistical recap"]
  node_score["Financial score"]
end

subgraph group_experience["App Experience"]
  node_dashboard["Dashboard<br/>[DashboardScreen.kt]"]
  node_viewmodel["Dashboard calculations"]
  node_search["Transaction search<br/>[NlpSearchEngine.kt]"]
  node_share["Image sharing"]
  node_export["CSV export<br/>[CsvExporter.kt]"]
  node_security["App security<br/>[SecurityManager.kt]"]
end

subgraph group_cloud["Optional Cloud"]
  node_cloudapi["Sync API<br/>[main.py]"]
  node_ml["Cloud ML analysis<br/>[ml_engine.py]"]
  node_encrypted[("Encrypted file storage<br/>[security.py]")]
end

node_user(("Mahari user"))
node_sms["M-Pesa SMS"]
node_device["Android device inbox"]
node_clouduser(("Syncing device"))

node_sms -->|"delivers alert"| node_receiver
node_device -->|"provides SMS history"| node_backfill
node_receiver -.->|"parses message"| node_parser
node_backfill -->|"parses history"| node_parser
node_parser -->|"categorizes transactions"| node_categorizer
node_categorizer -.->|"records transactions"| node_repository
node_repository -.->|"persists transactions"| node_database
node_user -->|"views finances"| node_dashboard
node_dashboard -.->|"requests calculations"| node_viewmodel
node_viewmodel -.->|"loads transactions"| node_repository
node_viewmodel -.->|"calculates budgets"| node_budget
node_viewmodel -.->|"builds recap"| node_recap
node_recap -.->|"uses statistics"| node_stats
node_recap -.->|"calculates score"| node_score
node_user -->|"searches transactions"| node_search
node_user -->|"shares dashboard"| node_share
node_user -.->|"exports data"| node_export
node_user -->|"authenticates"| node_security
node_clouduser -->|"syncs structured data"| node_cloudapi
node_cloudapi -->|"stores encrypted data"| node_encrypted
node_cloudapi -->|"analyzes transactions"| node_ml
node_clouduser -->|"requests data deletion"| node_cloudapi

click node_receiver "https://github.com/dilithegit/mahari/blob/main/app/src/main/java/com/example/mahari/data/receiver/SmsReceiver.kt"
click node_backfill "https://github.com/dilithegit/mahari/blob/main/app/src/main/java/com/example/mahari/data/parser/SmsBackfillManager.kt"
click node_parser "https://github.com/dilithegit/mahari/blob/main/app/src/main/java/com/example/mahari/data/parser/MpesaParser.kt"
click node_categorizer "https://github.com/dilithegit/mahari/blob/main/app/src/main/java/com/example/mahari/data/categorizer/Categorizer.kt"
click node_repository "https://github.com/dilithegit/mahari/blob/main/app/src/main/java/com/example/mahari/data/repository/TransactionRepository.kt"
click node_database "https://github.com/dilithegit/mahari/blob/main/app/src/main/java/com/example/mahari/data/db/MahariDatabase.kt"
click node_dashboard "https://github.com/dilithegit/mahari/blob/main/app/src/main/java/com/example/mahari/ui/dashboard/DashboardScreen.kt"
click node_viewmodel "https://github.com/dilithegit/mahari/blob/main/app/src/main/java/com/example/mahari/ui/dashboard/DashboardViewModel.kt"
click node_budget "https://github.com/dilithegit/mahari/blob/main/app/src/main/java/com/example/mahari/data/budget/BudgetEngine.kt"
click node_recap "https://github.com/dilithegit/mahari/blob/main/app/src/main/java/com/example/mahari/data/recap/RecapMlEngine.kt"
click node_stats "https://github.com/dilithegit/mahari/blob/main/app/src/main/java/com/example/mahari/data/recap/StatisticalRecapEngine.kt"
click node_score "https://github.com/dilithegit/mahari/blob/main/app/src/main/java/com/example/mahari/data/recap/FinancialScoreEngine.kt"
click node_search "https://github.com/dilithegit/mahari/blob/main/app/src/main/java/com/example/mahari/data/nlp/NlpSearchEngine.kt"
click node_share "https://github.com/dilithegit/mahari/blob/main/app/src/main/java/com/example/mahari/ui/share/ShareDashboardDialog.kt"
click node_export "https://github.com/dilithegit/mahari/blob/main/app/src/main/java/com/example/mahari/data/export/CsvExporter.kt"
click node_security "https://github.com/dilithegit/mahari/blob/main/app/src/main/java/com/example/mahari/data/security/SecurityManager.kt"
click node_cloudapi "https://github.com/dilithegit/mahari/blob/main/mahari_backend/main.py"
click node_ml "https://github.com/dilithegit/mahari/blob/main/mahari_backend/ml_engine.py"
click node_encrypted "https://github.com/dilithegit/mahari/blob/main/mahari_backend/security.py"

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_receiver,node_backfill,node_parser,node_categorizer,node_user toneBlue
class node_repository,node_database toneAmber
class node_budget,node_recap,node_stats,node_score toneMint
class node_dashboard,node_viewmodel,node_search,node_share,node_export,node_security toneRose
class node_cloudapi,node_ml,node_encrypted,node_sms,node_device,node_clouduser toneIndigo
```

## Components

### Transaction Capture

- [SMS receiver](https://github.com/dilithegit/mahari/blob/main/app/src/main/java/com/example/mahari/data/receiver/SmsReceiver.kt): `app/src/main/java/com/example/mahari/data/receiver/SmsReceiver.kt`
- [SMS backfill](https://github.com/dilithegit/mahari/blob/main/app/src/main/java/com/example/mahari/data/parser/SmsBackfillManager.kt): `app/src/main/java/com/example/mahari/data/parser/SmsBackfillManager.kt`
- [M-Pesa parser](https://github.com/dilithegit/mahari/blob/main/app/src/main/java/com/example/mahari/data/parser/MpesaParser.kt): `app/src/main/java/com/example/mahari/data/parser/MpesaParser.kt`
- [Transaction categorizer](https://github.com/dilithegit/mahari/blob/main/app/src/main/java/com/example/mahari/data/categorizer/Categorizer.kt): `app/src/main/java/com/example/mahari/data/categorizer/Categorizer.kt`

### Local Finance Data

- [Transaction repository](https://github.com/dilithegit/mahari/blob/main/app/src/main/java/com/example/mahari/data/repository/TransactionRepository.kt): `app/src/main/java/com/example/mahari/data/repository/TransactionRepository.kt`
- [Room database](https://github.com/dilithegit/mahari/blob/main/app/src/main/java/com/example/mahari/data/db/MahariDatabase.kt): `app/src/main/java/com/example/mahari/data/db/MahariDatabase.kt`

### Financial Insights

- [Budget engine](https://github.com/dilithegit/mahari/blob/main/app/src/main/java/com/example/mahari/data/budget/BudgetEngine.kt): `app/src/main/java/com/example/mahari/data/budget/BudgetEngine.kt`
- [On-device recap](https://github.com/dilithegit/mahari/blob/main/app/src/main/java/com/example/mahari/data/recap/RecapMlEngine.kt): `app/src/main/java/com/example/mahari/data/recap/RecapMlEngine.kt`
- [Statistical recap](https://github.com/dilithegit/mahari/blob/main/app/src/main/java/com/example/mahari/data/recap/StatisticalRecapEngine.kt): `app/src/main/java/com/example/mahari/data/recap/StatisticalRecapEngine.kt`
- [Financial score](https://github.com/dilithegit/mahari/blob/main/app/src/main/java/com/example/mahari/data/recap/FinancialScoreEngine.kt): `app/src/main/java/com/example/mahari/data/recap/FinancialScoreEngine.kt`

### App Experience

- [Dashboard](https://github.com/dilithegit/mahari/blob/main/app/src/main/java/com/example/mahari/ui/dashboard/DashboardScreen.kt): `app/src/main/java/com/example/mahari/ui/dashboard/DashboardScreen.kt`
- [Dashboard calculations](https://github.com/dilithegit/mahari/blob/main/app/src/main/java/com/example/mahari/ui/dashboard/DashboardViewModel.kt): `app/src/main/java/com/example/mahari/ui/dashboard/DashboardViewModel.kt`
- [Transaction search](https://github.com/dilithegit/mahari/blob/main/app/src/main/java/com/example/mahari/data/nlp/NlpSearchEngine.kt): `app/src/main/java/com/example/mahari/data/nlp/NlpSearchEngine.kt`
- [Image sharing](https://github.com/dilithegit/mahari/blob/main/app/src/main/java/com/example/mahari/ui/share/ShareDashboardDialog.kt): `app/src/main/java/com/example/mahari/ui/share/ShareDashboardDialog.kt`
- [CSV export](https://github.com/dilithegit/mahari/blob/main/app/src/main/java/com/example/mahari/data/export/CsvExporter.kt): `app/src/main/java/com/example/mahari/data/export/CsvExporter.kt`
- [App security](https://github.com/dilithegit/mahari/blob/main/app/src/main/java/com/example/mahari/data/security/SecurityManager.kt): `app/src/main/java/com/example/mahari/data/security/SecurityManager.kt`

### Optional Cloud

- [Sync API](https://github.com/dilithegit/mahari/blob/main/mahari_backend/main.py): `mahari_backend/main.py`
- [Cloud ML analysis](https://github.com/dilithegit/mahari/blob/main/mahari_backend/ml_engine.py): `mahari_backend/ml_engine.py`
- [Encrypted file storage](https://github.com/dilithegit/mahari/blob/main/mahari_backend/security.py): `mahari_backend/security.py`

### Other components

- **Mahari user**
- **M-Pesa SMS**
- **Android device inbox**
- **Syncing device**

## Connections

- M-Pesa SMS → SMS receiver: delivers alert (evidence: `README.md`)
- Android device inbox → SMS backfill: provides SMS history (evidence: `README.md`)
- SMS receiver → M-Pesa parser: parses message
- SMS backfill → M-Pesa parser: parses history (evidence: `README.md`)
- M-Pesa parser → Transaction categorizer: categorizes transactions (evidence: `README.md`)
- Transaction categorizer → Transaction repository: records transactions
- Transaction repository → Room database: persists transactions
- Mahari user → Dashboard: views finances (evidence: `README.md`)
- Dashboard → Dashboard calculations: requests calculations
- Dashboard calculations → Transaction repository: loads transactions
- Dashboard calculations → Budget engine: calculates budgets
- Dashboard calculations → On-device recap: builds recap
- On-device recap → Statistical recap: uses statistics
- On-device recap → Financial score: calculates score
- Mahari user → Transaction search: searches transactions (evidence: `README.md`)
- Mahari user → Image sharing: shares dashboard (evidence: `README.md`)
- Mahari user → CSV export: exports data
- Mahari user → App security: authenticates (evidence: `README.md`)
- Syncing device → Sync API: syncs structured data (evidence: `README.md`)
- Sync API → Encrypted file storage: stores encrypted data (evidence: `mahari_backend/main.py`)
- Sync API → Cloud ML analysis: analyzes transactions (evidence: `mahari_backend/main.py`)
- Syncing device → Sync API: requests data deletion (evidence: `README.md`)
