How ritesh-kanwar/cashiro works
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: CashiroDatabase.kt Data layer · CashiroNavHost.kt Navigation · AddTransactionUseCase.kt Use cases · TransactionsScreen.kt Money views
Components 18
Android app
Main Android/Kotlin application module with UI, storage, background execution, and platform integration.
- App startup · Application and activity bootstrap for DI, Compose host, and app-wide services.
app/src/main/java/com/ritesh/cashiro/CashiroApplication.kt - Main screen · Hosts the Compose UI and navigation graph.
app/src/main/java/com/ritesh/cashiro/MainActivity.kt - Navigation · Central navigation graph and destination definitions for the app UI.
app/src/main/java/com/ritesh/cashiro/presentation/navigation/CashiroNavHost.kt - Home & forms · 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 · 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 · 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 · 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 · 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 · 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 · Repositories, Room database, mappers, converters, preferences, and local services.
app/src/main/java/com/ritesh/cashiro/data/database/CashiroDatabase.kt - SMS ingest · SMS broadcast handling, worker execution, transaction processing, and mapping into persisted records.
app/src/main/java/com/ritesh/cashiro/receiver/SmsBroadcastReceiver.kt - PDF import · 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 · Webhook validation, payload building, scheduling, delivery, and sync management.
app/src/main/java/com/ritesh/cashiro/data/webhook/WebhookSyncManager.kt - Background jobs · WorkManager workers, receivers, notification scheduling, boot handling, and quick-setting services.
app/src/main/java/com/ritesh/cashiro/worker/SmsReaderWorker.kt - Currency & analytics · 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 · 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 · 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 · Gradle setup, flavor-specific sources, GitHub Actions, Fastlane metadata, and release automation.
app/build.gradle.kts
Connections 23
- 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.