# ritesh-kanwar/cashiro architecture

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

- Interactive diagram: https://gitdiagram.com/ritesh-kanwar/cashiro
- Repository: https://github.com/ritesh-kanwar/cashiro

## Overview

1. **Repository shape**
   - This is a multi-module Android/Kotlin project centered on a single app module plus a standalone `parser-core` library.
   - The app is organized into clear layers: `presentation`, `domain`, `data`, `di`, `utils`, with Android-specific entry points, workers, receivers, and services.

2. **App boundary and runtime**
   - The main runtime is an Android app built with Jetpack Compose and Material 3.
   - `CashiroApplication` bootstraps dependency injection and app-wide services; `MainActivity` hosts the Compose UI and navigation graph.

3. **Presentation layer**
   - UI is feature-first: screens and ViewModels are grouped by domain area such as home, transactions, budgets, categories, subscriptions, analytics, settings, chat, accounts, and onboarding.
   - State flows downward from ViewModels into Compose screens; reusable UI lives in `presentation/ui/components`, while navigation is centralized in `presentation/navigation`.

4. **Domain layer**
   - The domain layer holds use cases, rule-engine logic, and domain models for transaction rules.
   - It acts as the boundary between UI and storage/processing, especially for business logic like adding transactions, applying rules, initializing templates, and subscription management.

5. **Data layer and persistence**
   - Local persistence is Room-based, with entities and DAOs for transactions, categories, budgets, accounts, cards, subscriptions, exchange rates, rules, merchant mappings, chats, and unrecognized SMS.
   - The checked-in Room schema files show a long migration history, so database versioning/migrations are an important architectural concern.

6. **Transaction ingestion pipeline**
   - The primary input paths are SMS and PDF statements.
   - SMSs are received through `SmsBroadcastReceiver` and background workers; PDF statements are parsed through `PdfStatementParser`.
   - Parsed records are mapped into app transactions via `SmsTransactionProcessor` and mapper classes, then persisted in Room.

7. **Parser subsystem**
   - `parser-core` is a dedicated parsing library with a large registry of bank-specific SMS parsers and shared parsing primitives.
   - This module is a major boundary: it isolates bank/region-specific transaction extraction from the rest of the app, and it is heavily unit-tested with parser fixtures and bank-specific tests.

8. **Rules, categorization, and enrichment**
   - After ingestion, transactions can be enriched by rule application, merchant mapping, and category/subcategory assignment.
   - The rule engine and related repositories store and apply user-defined transaction rules, including retrospective application to past transactions.

9. **Currency and analytics**
   - Multi-currency support is first-class: exchange rates are stored locally, and conversion logic is handled through currency repositories/services.
   - Analytics screens consume aggregated transaction data to render charts, summaries, and budget progress views.

10. **AI chat and on-device intelligence**
   - The chat subsystem uses a local LLM abstraction (`LlmService`, `LlmRepository`, `AiContextRepository`) to answer questions about the user’s financial data.
   - The README emphasizes on-device processing; there is no central backend for AI inference, so the data flow stays local to the device.

11. **Webhooks and outbound sync**
   - Webhook support is the main intentional networked feature: users can define endpoints, and the app schedules delivery of transaction/budget data.
   - `WebhookSyncManager`, `WebhookSyncWorker`, payload builders, validation, and header encoding form the outbound pipeline, with scheduling driven by receivers and workers.

12. **Background execution and device integration**
   - The app relies on Android background primitives: WorkManager workers, broadcast receivers, notification scheduling, boot handling, and quick-setting tile services.
   - This is how SMS ingestion, webhook sync, reminders, and shortcuts continue outside the foreground UI.

13. **Settings, privacy, and security**
   - Settings cover app lock/biometric protection, appearance, notification preferences, data privacy, SMS settings, rules, webhooks, and developer options.
   - Privacy is a core boundary: data is stored locally, and the app includes encryption/utilities plus biometric auth rather than server-based accounts.

14. **Build variants and tooling**
   - There are at least two build flavors/paths: `standard` and `fdroid`.
   - The `fdroid` source set replaces Google Play-dependent components like in-app review/update managers, which affects the dependency graph and packaging behavior.
   - CI/release automation is present via GitHub Actions, Fastlane metadata, release scripts, and baseline profiles for release performance.

15. **Main data flow to diagram**
   - The clearest architecture path is: user input or system event → parser/worker/receiver → processing/rules/enrichment → Room persistence → ViewModels/UI.
   - Secondary flows branch from the same data store into analytics, CSV export, backups, webhook delivery, notifications, and on-device chat.

Main entry points: [`app/src/main/java/com/ritesh/cashiro/data/database/CashiroDatabase.kt`](https://github.com/ritesh-kanwar/cashiro/blob/main/app/src/main/java/com/ritesh/cashiro/data/database/CashiroDatabase.kt) (Data layer), [`app/src/main/java/com/ritesh/cashiro/presentation/navigation/CashiroNavHost.kt`](https://github.com/ritesh-kanwar/cashiro/blob/main/app/src/main/java/com/ritesh/cashiro/presentation/navigation/CashiroNavHost.kt) (Navigation), [`app/src/main/java/com/ritesh/cashiro/domain/usecase/AddTransactionUseCase.kt`](https://github.com/ritesh-kanwar/cashiro/blob/main/app/src/main/java/com/ritesh/cashiro/domain/usecase/AddTransactionUseCase.kt) (Use cases), [`app/src/main/java/com/ritesh/cashiro/presentation/ui/features/transactions/TransactionsScreen.kt`](https://github.com/ritesh-kanwar/cashiro/blob/main/app/src/main/java/com/ritesh/cashiro/presentation/ui/features/transactions/TransactionsScreen.kt) (Money views)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_repo_app["Android app"]
  node_cashiro_app["App startup<br/>android entrypoint"]
  node_main_activity["Main screen<br/>compose host<br/>[MainActivity.kt]"]
  node_presentation_nav["Navigation<br/>compose routing<br/>[CashiroNavHost.kt]"]
  node_home_features["Home & forms<br/>feature ui<br/>[HomeScreen.kt]"]
  node_money_features["Money views<br/>feature ui"]
  node_settings_features["Settings hub<br/>feature ui<br/>[SettingsScreen.kt]"]
  node_chat_feature["AI chat<br/>feature ui<br/>[ChatScreen.kt]"]
  node_domain_usecases["Use cases<br/>domain orchestration"]
  node_rule_engine["Rules engine<br/>domain logic<br/>[RuleEngine.kt]"]
  node_app_data[("Data layer<br/>repositories & persistence<br/>[CashiroDatabase.kt]")]
  node_sms_pipeline["SMS ingest<br/>ingestion pipeline"]
  node_pdf_parser["PDF import<br/>statement parser"]
  node_webhook_sync["Webhook sync<br/>outbound sync"]
  node_background_runtime["Background jobs<br/>android background<br/>[SmsReaderWorker.kt]"]
  node_currency_analytics["Currency & analytics<br/>data services"]
  node_local_ai["Local AI<br/>llm services<br/>[LlmServiceImpl.kt]"]
end

subgraph group_repo_parser["Parser core"]
  node_parser_core_lib["parser-core"]
end

subgraph group_repo_tooling["Build & release"]
  node_build_release["Build & release<br/>tooling<br/>[build.gradle.kts]"]
end

node_cashiro_app -->|"launches"| node_main_activity
node_main_activity -->|"hosts"| node_presentation_nav
node_presentation_nav -->|"routes"| node_home_features
node_presentation_nav -->|"routes"| node_money_features
node_presentation_nav -->|"routes"| node_settings_features
node_presentation_nav -->|"routes"| node_chat_feature
node_home_features -->|"invokes"| node_domain_usecases
node_money_features -->|"invokes"| node_domain_usecases
node_settings_features -->|"invokes"| node_domain_usecases
node_domain_usecases -->|"uses"| node_rule_engine
node_rule_engine -->|"stores"| node_app_data
node_sms_pipeline -->|"parses"| node_parser_core_lib
node_sms_pipeline -->|"persists"| node_app_data
node_pdf_parser -->|"imports"| node_app_data
node_background_runtime -->|"runs"| node_sms_pipeline
node_background_runtime -->|"triggers"| node_webhook_sync
node_webhook_sync -->|"reads"| node_app_data
node_currency_analytics -->|"reads"| node_app_data
node_money_features -->|"visualizes"| node_currency_analytics
node_chat_feature -->|"queries"| node_local_ai
node_local_ai -->|"context"| node_app_data
node_build_release -->|"packages"| node_cashiro_app
node_build_release -->|"builds"| node_parser_core_lib

click node_cashiro_app "https://github.com/ritesh-kanwar/cashiro/blob/main/app/src/main/java/com/ritesh/cashiro/CashiroApplication.kt"
click node_main_activity "https://github.com/ritesh-kanwar/cashiro/blob/main/app/src/main/java/com/ritesh/cashiro/MainActivity.kt"
click node_presentation_nav "https://github.com/ritesh-kanwar/cashiro/blob/main/app/src/main/java/com/ritesh/cashiro/presentation/navigation/CashiroNavHost.kt"
click node_home_features "https://github.com/ritesh-kanwar/cashiro/blob/main/app/src/main/java/com/ritesh/cashiro/presentation/ui/features/home/HomeScreen.kt"
click node_money_features "https://github.com/ritesh-kanwar/cashiro/blob/main/app/src/main/java/com/ritesh/cashiro/presentation/ui/features/transactions/TransactionsScreen.kt"
click node_settings_features "https://github.com/ritesh-kanwar/cashiro/blob/main/app/src/main/java/com/ritesh/cashiro/presentation/ui/features/settings/SettingsScreen.kt"
click node_chat_feature "https://github.com/ritesh-kanwar/cashiro/blob/main/app/src/main/java/com/ritesh/cashiro/presentation/ui/features/chat/ChatScreen.kt"
click node_domain_usecases "https://github.com/ritesh-kanwar/cashiro/blob/main/app/src/main/java/com/ritesh/cashiro/domain/usecase/AddTransactionUseCase.kt"
click node_rule_engine "https://github.com/ritesh-kanwar/cashiro/blob/main/app/src/main/java/com/ritesh/cashiro/domain/service/RuleEngine.kt"
click node_app_data "https://github.com/ritesh-kanwar/cashiro/blob/main/app/src/main/java/com/ritesh/cashiro/data/database/CashiroDatabase.kt"
click node_sms_pipeline "https://github.com/ritesh-kanwar/cashiro/blob/main/app/src/main/java/com/ritesh/cashiro/receiver/SmsBroadcastReceiver.kt"
click node_pdf_parser "https://github.com/ritesh-kanwar/cashiro/blob/main/app/src/main/java/com/ritesh/cashiro/data/parser/pdf/PdfStatementParser.kt"
click node_webhook_sync "https://github.com/ritesh-kanwar/cashiro/blob/main/app/src/main/java/com/ritesh/cashiro/data/webhook/WebhookSyncManager.kt"
click node_background_runtime "https://github.com/ritesh-kanwar/cashiro/blob/main/app/src/main/java/com/ritesh/cashiro/worker/SmsReaderWorker.kt"
click node_currency_analytics "https://github.com/ritesh-kanwar/cashiro/blob/main/app/src/main/java/com/ritesh/cashiro/data/currency/CurrencyConversionService.kt"
click node_local_ai "https://github.com/ritesh-kanwar/cashiro/blob/main/app/src/main/java/com/ritesh/cashiro/data/service/LlmServiceImpl.kt"
click node_parser_core_lib "https://github.com/ritesh-kanwar/cashiro/blob/main/parser-core/src/main/kotlin/com/ritesh/parser/core/bank/BankParserRegistry.kt"
click node_build_release "https://github.com/ritesh-kanwar/cashiro/blob/main/app/build.gradle.kts"

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_cashiro_app,node_main_activity,node_presentation_nav,node_home_features,node_money_features,node_settings_features,node_chat_feature,node_domain_usecases,node_rule_engine,node_app_data,node_sms_pipeline,node_pdf_parser,node_webhook_sync,node_background_runtime,node_currency_analytics,node_local_ai toneBlue
class node_parser_core_lib toneAmber
class node_build_release toneMint
```

## Components

### Android app

Main Android/Kotlin application module with UI, storage, background execution, and platform integration.

- [App startup](https://github.com/ritesh-kanwar/cashiro/blob/main/app/src/main/java/com/ritesh/cashiro/CashiroApplication.kt): android entrypoint · Application and activity bootstrap for DI, Compose host, and app-wide services. · `app/src/main/java/com/ritesh/cashiro/CashiroApplication.kt`
- [Main screen](https://github.com/ritesh-kanwar/cashiro/blob/main/app/src/main/java/com/ritesh/cashiro/MainActivity.kt): compose host · Hosts the Compose UI and navigation graph. · `app/src/main/java/com/ritesh/cashiro/MainActivity.kt`
- [Navigation](https://github.com/ritesh-kanwar/cashiro/blob/main/app/src/main/java/com/ritesh/cashiro/presentation/navigation/CashiroNavHost.kt): compose routing · Central navigation graph and destination definitions for the app UI. · `app/src/main/java/com/ritesh/cashiro/presentation/navigation/CashiroNavHost.kt`
- [Home & forms](https://github.com/ritesh-kanwar/cashiro/blob/main/app/src/main/java/com/ritesh/cashiro/presentation/ui/features/home/HomeScreen.kt): feature ui · Primary user-facing screens for home, add, accounts, profile, onboarding, and related view models. · `app/src/main/java/com/ritesh/cashiro/presentation/ui/features/home/HomeScreen.kt`
- [Money views](https://github.com/ritesh-kanwar/cashiro/blob/main/app/src/main/java/com/ritesh/cashiro/presentation/ui/features/transactions/TransactionsScreen.kt): feature ui · Transactions, budgets, categories, subscriptions, and analytics screens built from shared Compose components. · `app/src/main/java/com/ritesh/cashiro/presentation/ui/features/transactions/TransactionsScreen.kt`
- [Settings hub](https://github.com/ritesh-kanwar/cashiro/blob/main/app/src/main/java/com/ritesh/cashiro/presentation/ui/features/settings/SettingsScreen.kt): feature ui · Settings, appearance, app lock, privacy, SMS, rules, webhooks, developer, and about screens. · `app/src/main/java/com/ritesh/cashiro/presentation/ui/features/settings/SettingsScreen.kt`
- [AI chat](https://github.com/ritesh-kanwar/cashiro/blob/main/app/src/main/java/com/ritesh/cashiro/presentation/ui/features/chat/ChatScreen.kt): feature ui · On-device finance chat interface backed by local context and LLM abstractions. · `app/src/main/java/com/ritesh/cashiro/presentation/ui/features/chat/ChatScreen.kt`
- [Use cases](https://github.com/ritesh-kanwar/cashiro/blob/main/app/src/main/java/com/ritesh/cashiro/domain/usecase/AddTransactionUseCase.kt): domain orchestration · Business actions such as adding transactions, applying rules, initializing templates, and managing subscriptions. · `app/src/main/java/com/ritesh/cashiro/domain/usecase/AddTransactionUseCase.kt`
- [Rules engine](https://github.com/ritesh-kanwar/cashiro/blob/main/app/src/main/java/com/ritesh/cashiro/domain/service/RuleEngine.kt): domain logic · Transaction rule models, rule engine, and template services for categorization and retrospective application. · `app/src/main/java/com/ritesh/cashiro/domain/service/RuleEngine.kt`
- [Data layer](https://github.com/ritesh-kanwar/cashiro/blob/main/app/src/main/java/com/ritesh/cashiro/data/database/CashiroDatabase.kt): repositories & persistence · Repositories, Room database, mappers, converters, preferences, and local services. · `app/src/main/java/com/ritesh/cashiro/data/database/CashiroDatabase.kt`
- [SMS ingest](https://github.com/ritesh-kanwar/cashiro/blob/main/app/src/main/java/com/ritesh/cashiro/receiver/SmsBroadcastReceiver.kt): ingestion pipeline · SMS broadcast handling, worker execution, transaction processing, and mapping into persisted records. · `app/src/main/java/com/ritesh/cashiro/receiver/SmsBroadcastReceiver.kt`
- [PDF import](https://github.com/ritesh-kanwar/cashiro/blob/main/app/src/main/java/com/ritesh/cashiro/data/parser/pdf/PdfStatementParser.kt): statement parser · PDF statement parsing path used for imported documents and settings-driven privacy flows. · `app/src/main/java/com/ritesh/cashiro/data/parser/pdf/PdfStatementParser.kt`
- [Webhook sync](https://github.com/ritesh-kanwar/cashiro/blob/main/app/src/main/java/com/ritesh/cashiro/data/webhook/WebhookSyncManager.kt): outbound sync · Webhook validation, payload building, scheduling, delivery, and sync management. · `app/src/main/java/com/ritesh/cashiro/data/webhook/WebhookSyncManager.kt`
- [Background jobs](https://github.com/ritesh-kanwar/cashiro/blob/main/app/src/main/java/com/ritesh/cashiro/worker/SmsReaderWorker.kt): android background · WorkManager workers, receivers, notification scheduling, boot handling, and quick-setting services. · `app/src/main/java/com/ritesh/cashiro/worker/SmsReaderWorker.kt`
- [Currency & analytics](https://github.com/ritesh-kanwar/cashiro/blob/main/app/src/main/java/com/ritesh/cashiro/data/currency/CurrencyConversionService.kt): data services · Exchange rates, conversion services, and aggregated reporting used by analytics and account views. · `app/src/main/java/com/ritesh/cashiro/data/currency/CurrencyConversionService.kt`
- [Local AI](https://github.com/ritesh-kanwar/cashiro/blob/main/app/src/main/java/com/ritesh/cashiro/data/service/LlmServiceImpl.kt): llm services · On-device LLM service, repository, and AI context storage for chat and analysis. · `app/src/main/java/com/ritesh/cashiro/data/service/LlmServiceImpl.kt`

### Parser core

Standalone parsing library for bank-specific SMS and statement extraction.

- [parser-core](https://github.com/ritesh-kanwar/cashiro/blob/main/parser-core/src/main/kotlin/com/ritesh/parser/core/bank/BankParserRegistry.kt): library · Standalone SMS parsing library with shared primitives and a large bank parser registry. · `parser-core/src/main/kotlin/com/ritesh/parser/core/bank/BankParserRegistry.kt`

### Build & release

Variants, CI, and release automation around the project.

- [Build & release](https://github.com/ritesh-kanwar/cashiro/blob/main/app/build.gradle.kts): tooling · Gradle setup, flavor-specific sources, GitHub Actions, Fastlane metadata, and release automation. · `app/build.gradle.kts`

## Connections

- App startup → Main screen: launches · Application startup hands off to the Compose entry activity.
- Main screen → Navigation: hosts · The activity renders the app navigation graph.
- Navigation → Home & forms: routes · Navigation connects to core home and form-driven screens.
- Navigation → Money views: routes · Navigation connects to transaction, budget, category, subscription, and analytics screens.
- Navigation → Settings hub: routes · Navigation connects to settings and administrative screens.
- Navigation → AI chat: routes · Navigation connects to the finance chat UI.
- Home & forms → Use cases: invokes · View models and screens trigger business actions through use cases.
- Money views → Use cases: invokes · Money-management screens use domain actions for reads and writes.
- Settings hub → Use cases: invokes · Settings flows initialize templates and update subscriptions or rules.
- Use cases → Rules engine: uses · Use cases delegate transaction classification and rule application to the rule engine.
- Rules engine → Data layer: stores · Rules and applications are persisted through repositories and Room.
- SMS ingest → parser-core: parses · Incoming SMS text is classified and parsed using the shared parser library.
- SMS ingest → Data layer: persists · Parsed transactions and unrecognized SMS are stored locally.
- PDF import → Data layer: imports · Parsed statement records are mapped into local transaction storage.
- Background jobs → SMS ingest: runs · Workers and receivers keep ingestion active outside the foreground app.
- Background jobs → Webhook sync: triggers · Scheduled background execution drives webhook delivery.
- Webhook sync → Data layer: reads · Webhook payloads are assembled from locally stored transactions and budgets.
- Currency & analytics → Data layer: reads · Analytics and conversion logic consume persisted balances, rates, and transactions.
- Money views → Currency & analytics: visualizes · Analytics and account screens render grouped totals and converted summaries.
- AI chat → Local AI: queries · Chat UI calls into the local LLM and context repositories.
- Local AI → Data layer: context · AI context is built from local financial data.
- Build & release → App startup: packages · Build variants and release automation package the Android app.
- Build & release → parser-core: builds · The standalone parser library is built and tested as part of the repo.