# jackworksp/kanakku architecture

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

- Interactive diagram: https://gitdiagram.com/jackworksp/kanakku
- Repository: https://github.com/jackworksp/kanakku

## Overview

#### Purpose and Runtime
Kanakku is a native Android personal-finance tracker. It records and analyzes transactions, budgets, categories, recurring payments, savings goals, exports, device widgets, SMS-derived transactions, notifications, and backups. The Gradle Android app module is `app/build.gradle.kts`; the application starts through `app/src/main/java/com/example/kanakku/KanakkuApplication.kt` and `app/src/main/java/com/example/kanakku/MainActivity.kt`.

#### Composition and UI Boundary
The presentation layer is Kotlin/Jetpack Compose-style UI organized around screens, navigation, and stateful ViewModels. `MainActivity` hosts navigation from `app/src/main/java/com/example/kanakku/ui/navigation/KanakkuNavigation.kt`; feature ViewModels mediate UI events and repository/domain results, e.g. `app/src/main/java/com/example/kanakku/ui/MainViewModel.kt` and `app/src/main/java/com/example/kanakku/ui/budget/BudgetViewModel.kt`. Screens should not directly own persistence or external integrations.

#### Dependency Assembly
Dependency injection centralizes construction of database, repositories, and application services in `app/src/main/java/com/example/kanakku/di/AppModule.kt`, `app/src/main/java/com/example/kanakku/di/DatabaseModule.kt`, and `app/src/main/java/com/example/kanakku/di/RepositoryModule.kt`. This is the principal boundary for replacing persistence/integration implementations and for lifecycle-scoped Android dependencies.

#### Transaction Data Core
Room-backed local storage is the system of record. `app/src/main/java/com/example/kanakku/data/database/KanakkuDatabase.kt` defines the database; DAOs such as `app/src/main/java/com/example/kanakku/data/database/dao/TransactionDao.kt` isolate SQL access; repositories such as `app/src/main/java/com/example/kanakku/data/repository/TransactionRepository.kt` map entities and coordinate transaction-facing operations. Stored domains include transactions, budgets, category overrides/mappings, recurring transactions, savings goals/contributions, sync metadata, and unreported SMS.

#### Finance Domain Processing
Pure/domain-oriented services calculate derived financial state above repository data: analytics in `app/src/main/java/com/example/kanakku/domain/analytics/AnalyticsCalculator.kt`, budget progress in `app/src/main/java/com/example/kanakku/domain/budget/BudgetCalculator.kt`, and recurring-payment detection in `app/src/main/java/com/example/kanakku/domain/recurring/RecurringTransactionDetector.kt`. Savings computations and category suggestions follow the same separation, allowing UI, widgets, alerts, and exports to consume shared business outcomes.

#### SMS Ingestion and Alerts
An Android SMS receiver initiates the ingestion pipeline: `app/src/main/java/com/example/kanakku/receiver/SmsBroadcastReceiver.kt` delegates background handling to `app/src/main/java/com/example/kanakku/service/SmsProcessingService.kt`, which reads/parses bank messages through `app/src/main/java/com/example/kanakku/data/sms/BankSmsParser.kt`. Parsed transactions enter the repository/database flow; failures or unresolved messages can remain reportable. Transaction and spending conditions feed Android notification managers under `app/src/main/java/com/example/kanakku/notification/`.

#### Backup, Export, and Device Integrations
Backup serialization/encryption is separated from storage targets: `app/src/main/java/com/example/kanakku/data/backup/BackupSerializer.kt`, `app/src/main/java/com/example/kanakku/data/backup/EncryptionService.kt`, and `app/src/main/java/com/example/kanakku/data/backup/DriveBackupRepository.kt`. Google authentication/Drive are external services via `GoogleAuthHelper` and `GoogleDriveService`; local backup is an alternate target. CSV/PDF output flows through `app/src/main/java/com/example/kanakku/data/repository/ExportRepository.kt`. Home-screen widgets query a dedicated data facade and update through scheduled work in `app/src/main/java/com/example/kanakku/widget/data/WidgetDataRepository.kt` and `app/src/main/java/com/example/kanakku/widget/worker/WidgetUpdateWorker.kt`.

Main entry points: [`app/src/main/java/com/example/kanakku/data/repository/TransactionRepository.kt`](https://github.com/jackworksp/kanakku/blob/master/app/src/main/java/com/example/kanakku/data/repository/TransactionRepository.kt) (Transaction Repository), [`app/src/main/java/com/example/kanakku/data/database/KanakkuDatabase.kt`](https://github.com/jackworksp/kanakku/blob/master/app/src/main/java/com/example/kanakku/data/database/KanakkuDatabase.kt) (Kanakku Database), [`app/src/main/java/com/example/kanakku/ui/MainViewModel.kt`](https://github.com/jackworksp/kanakku/blob/master/app/src/main/java/com/example/kanakku/ui/MainViewModel.kt) (Feature ViewModels), [`app/src/main/java/com/example/kanakku/di/AppModule.kt`](https://github.com/jackworksp/kanakku/blob/master/app/src/main/java/com/example/kanakku/di/AppModule.kt) (Dependency Assembly)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App & UI"]
  node_application{{"Kanakku Application<br/>Android application"}}
  node_activity["Main Activity<br/>Compose host<br/>[MainActivity.kt]"]
  node_navigation["Navigation<br/>screen router"]
  node_viewmodels["Feature ViewModels<br/>presentation state<br/>[MainViewModel.kt]"]
  node_di["Dependency Assembly<br/>DI modules<br/>[AppModule.kt]"]
end

subgraph group_core["Finance Core"]
  node_transaction_repo["Transaction Repository<br/>data repository"]
  node_daos["Room DAOs<br/>SQL access<br/>[TransactionDao.kt]"]
  node_database[("Kanakku Database<br/>Room database<br/>[KanakkuDatabase.kt]")]
  node_finance_domain["Finance Calculators<br/>domain services"]
end

subgraph group_ingest["SMS &amp; Alerts"]
  node_sms_receiver["SMS Receiver<br/>Android receiver"]
  node_sms_service["SMS Processing<br/>background service"]
  node_sms_parser["Bank SMS Parser<br/>message parser<br/>[BankSmsParser.kt]"]
  node_notifications["Notifications<br/>Android alert managers"]
end

subgraph group_integrations["Backup &amp; Device"]
  node_backup_serializer["Backup Serialization<br/>backup formatter"]
  node_encryption["Encryption Service<br/>backup encryption"]
  node_drive_backup["Drive Backup Repository<br/>backup target adapter"]
  node_google_drive(("Google Auth &amp; Drive<br/>external cloud service"))
  node_export_repo["Export Repository<br/>CSV/PDF export"]
  node_widget_data["Widget Data Facade<br/>widget repository"]
  node_widget_worker["Widget Update Worker<br/>scheduled worker"]
end

node_application -->|"initializes"| node_di
node_activity -->|"hosts"| node_navigation
node_navigation -->|"screens use"| node_viewmodels
node_di -->|"provides"| node_transaction_repo
node_di -->|"provides"| node_database
node_viewmodels -->|"reads and writes"| node_transaction_repo
node_viewmodels -->|"uses derived state"| node_finance_domain
node_transaction_repo -->|"uses"| node_daos
node_daos -->|"queries"| node_database
node_finance_domain -->|"consumes finance data"| node_transaction_repo
node_sms_receiver -->|"delegates SMS"| node_sms_service
node_sms_service -->|"parses messages"| node_sms_parser
node_sms_parser -->|"creates parsed transactions"| node_transaction_repo
node_finance_domain -->|"triggers spending alerts"| node_notifications
node_backup_serializer -->|"serializes stored data"| node_database
node_encryption -->|"encrypts backup payload"| node_backup_serializer
node_drive_backup -->|"uses"| node_encryption
node_drive_backup -->|"uploads via"| node_google_drive
node_export_repo -->|"exports finance data"| node_database
node_widget_worker -->|"refreshes"| node_widget_data
node_widget_data -->|"queries summarized data"| node_transaction_repo

click node_application "https://github.com/jackworksp/kanakku/blob/master/app/src/main/java/com/example/kanakku/KanakkuApplication.kt"
click node_activity "https://github.com/jackworksp/kanakku/blob/master/app/src/main/java/com/example/kanakku/MainActivity.kt"
click node_navigation "https://github.com/jackworksp/kanakku/blob/master/app/src/main/java/com/example/kanakku/ui/navigation/KanakkuNavigation.kt"
click node_viewmodels "https://github.com/jackworksp/kanakku/blob/master/app/src/main/java/com/example/kanakku/ui/MainViewModel.kt"
click node_di "https://github.com/jackworksp/kanakku/blob/master/app/src/main/java/com/example/kanakku/di/AppModule.kt"
click node_transaction_repo "https://github.com/jackworksp/kanakku/blob/master/app/src/main/java/com/example/kanakku/data/repository/TransactionRepository.kt"
click node_daos "https://github.com/jackworksp/kanakku/blob/master/app/src/main/java/com/example/kanakku/data/database/dao/TransactionDao.kt"
click node_database "https://github.com/jackworksp/kanakku/blob/master/app/src/main/java/com/example/kanakku/data/database/KanakkuDatabase.kt"
click node_finance_domain "https://github.com/jackworksp/kanakku/blob/master/app/src/main/java/com/example/kanakku/domain/analytics/AnalyticsCalculator.kt"
click node_sms_receiver "https://github.com/jackworksp/kanakku/blob/master/app/src/main/java/com/example/kanakku/receiver/SmsBroadcastReceiver.kt"
click node_sms_service "https://github.com/jackworksp/kanakku/blob/master/app/src/main/java/com/example/kanakku/service/SmsProcessingService.kt"
click node_sms_parser "https://github.com/jackworksp/kanakku/blob/master/app/src/main/java/com/example/kanakku/data/sms/BankSmsParser.kt"
click node_backup_serializer "https://github.com/jackworksp/kanakku/blob/master/app/src/main/java/com/example/kanakku/data/backup/BackupSerializer.kt"
click node_encryption "https://github.com/jackworksp/kanakku/blob/master/app/src/main/java/com/example/kanakku/data/backup/EncryptionService.kt"
click node_drive_backup "https://github.com/jackworksp/kanakku/blob/master/app/src/main/java/com/example/kanakku/data/backup/DriveBackupRepository.kt"
click node_export_repo "https://github.com/jackworksp/kanakku/blob/master/app/src/main/java/com/example/kanakku/data/repository/ExportRepository.kt"
click node_widget_data "https://github.com/jackworksp/kanakku/blob/master/app/src/main/java/com/example/kanakku/widget/data/WidgetDataRepository.kt"
click node_widget_worker "https://github.com/jackworksp/kanakku/blob/master/app/src/main/java/com/example/kanakku/widget/worker/WidgetUpdateWorker.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_application,node_activity,node_navigation,node_viewmodels,node_di toneBlue
class node_transaction_repo,node_daos,node_database,node_finance_domain toneAmber
class node_sms_receiver,node_sms_service,node_sms_parser,node_notifications toneMint
class node_backup_serializer,node_encryption,node_drive_backup,node_google_drive,node_export_repo,node_widget_data,node_widget_worker toneRose
```

## Components

### App & UI

- [Kanakku Application](https://github.com/jackworksp/kanakku/blob/master/app/src/main/java/com/example/kanakku/KanakkuApplication.kt): Android application · Initializes application-scoped dependencies. · `app/src/main/java/com/example/kanakku/KanakkuApplication.kt`
- [Main Activity](https://github.com/jackworksp/kanakku/blob/master/app/src/main/java/com/example/kanakku/MainActivity.kt): Compose host · `app/src/main/java/com/example/kanakku/MainActivity.kt`
- [Navigation](https://github.com/jackworksp/kanakku/blob/master/app/src/main/java/com/example/kanakku/ui/navigation/KanakkuNavigation.kt): screen router · `app/src/main/java/com/example/kanakku/ui/navigation/KanakkuNavigation.kt`
- [Feature ViewModels](https://github.com/jackworksp/kanakku/blob/master/app/src/main/java/com/example/kanakku/ui/MainViewModel.kt): presentation state · Mediates UI events and repository/domain results. · `app/src/main/java/com/example/kanakku/ui/MainViewModel.kt`
- [Dependency Assembly](https://github.com/jackworksp/kanakku/blob/master/app/src/main/java/com/example/kanakku/di/AppModule.kt): DI modules · Constructs database, repositories, and services. · `app/src/main/java/com/example/kanakku/di/AppModule.kt`

### Finance Core

- [Transaction Repository](https://github.com/jackworksp/kanakku/blob/master/app/src/main/java/com/example/kanakku/data/repository/TransactionRepository.kt): data repository · Maps entities and coordinates transaction operations. · `app/src/main/java/com/example/kanakku/data/repository/TransactionRepository.kt`
- [Room DAOs](https://github.com/jackworksp/kanakku/blob/master/app/src/main/java/com/example/kanakku/data/database/dao/TransactionDao.kt): SQL access · `app/src/main/java/com/example/kanakku/data/database/dao/TransactionDao.kt`
- [Kanakku Database](https://github.com/jackworksp/kanakku/blob/master/app/src/main/java/com/example/kanakku/data/database/KanakkuDatabase.kt): Room database · System of record for finance and ingestion state. · `app/src/main/java/com/example/kanakku/data/database/KanakkuDatabase.kt`
- [Finance Calculators](https://github.com/jackworksp/kanakku/blob/master/app/src/main/java/com/example/kanakku/domain/analytics/AnalyticsCalculator.kt): domain services · Shared analytics, budget progress, and recurring-payment logic. · `app/src/main/java/com/example/kanakku/domain/analytics/AnalyticsCalculator.kt`

### SMS & Alerts

- [SMS Receiver](https://github.com/jackworksp/kanakku/blob/master/app/src/main/java/com/example/kanakku/receiver/SmsBroadcastReceiver.kt): Android receiver · `app/src/main/java/com/example/kanakku/receiver/SmsBroadcastReceiver.kt`
- [SMS Processing](https://github.com/jackworksp/kanakku/blob/master/app/src/main/java/com/example/kanakku/service/SmsProcessingService.kt): background service · `app/src/main/java/com/example/kanakku/service/SmsProcessingService.kt`
- [Bank SMS Parser](https://github.com/jackworksp/kanakku/blob/master/app/src/main/java/com/example/kanakku/data/sms/BankSmsParser.kt): message parser · `app/src/main/java/com/example/kanakku/data/sms/BankSmsParser.kt`
- **Notifications**: Android alert managers

### Backup & Device

- [Backup Serialization](https://github.com/jackworksp/kanakku/blob/master/app/src/main/java/com/example/kanakku/data/backup/BackupSerializer.kt): backup formatter · `app/src/main/java/com/example/kanakku/data/backup/BackupSerializer.kt`
- [Encryption Service](https://github.com/jackworksp/kanakku/blob/master/app/src/main/java/com/example/kanakku/data/backup/EncryptionService.kt): backup encryption · `app/src/main/java/com/example/kanakku/data/backup/EncryptionService.kt`
- [Drive Backup Repository](https://github.com/jackworksp/kanakku/blob/master/app/src/main/java/com/example/kanakku/data/backup/DriveBackupRepository.kt): backup target adapter · `app/src/main/java/com/example/kanakku/data/backup/DriveBackupRepository.kt`
- **Google Auth & Drive**: external cloud service
- [Export Repository](https://github.com/jackworksp/kanakku/blob/master/app/src/main/java/com/example/kanakku/data/repository/ExportRepository.kt): CSV/PDF export · `app/src/main/java/com/example/kanakku/data/repository/ExportRepository.kt`
- [Widget Data Facade](https://github.com/jackworksp/kanakku/blob/master/app/src/main/java/com/example/kanakku/widget/data/WidgetDataRepository.kt): widget repository · `app/src/main/java/com/example/kanakku/widget/data/WidgetDataRepository.kt`
- [Widget Update Worker](https://github.com/jackworksp/kanakku/blob/master/app/src/main/java/com/example/kanakku/widget/worker/WidgetUpdateWorker.kt): scheduled worker · `app/src/main/java/com/example/kanakku/widget/worker/WidgetUpdateWorker.kt`

## Connections

- Kanakku Application → Dependency Assembly: initializes
- Main Activity → Navigation: hosts
- Navigation → Feature ViewModels: screens use
- Dependency Assembly → Transaction Repository: provides
- Dependency Assembly → Kanakku Database: provides
- Feature ViewModels → Transaction Repository: reads and writes
- Feature ViewModels → Finance Calculators: uses derived state
- Transaction Repository → Room DAOs: uses
- Room DAOs → Kanakku Database: queries
- Finance Calculators → Transaction Repository: consumes finance data
- SMS Receiver → SMS Processing: delegates SMS
- SMS Processing → Bank SMS Parser: parses messages
- Bank SMS Parser → Transaction Repository: creates parsed transactions
- Finance Calculators → Notifications: triggers spending alerts
- Backup Serialization → Kanakku Database: serializes stored data
- Encryption Service → Backup Serialization: encrypts backup payload
- Drive Backup Repository → Encryption Service: uses
- Drive Backup Repository → Google Auth & Drive: uploads via
- Export Repository → Kanakku Database: exports finance data
- Widget Update Worker → Widget Data Facade: refreshes
- Widget Data Facade → Transaction Repository: queries summarized data