# hariharen9/spendwiser-app architecture

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

- Interactive diagram: https://gitdiagram.com/hariharen9/spendwiser-app
- Repository: https://github.com/hariharen9/spendwiser-app

## Overview

SpendWiser is a local-first personal-finance app. Users onboard, record or import transactions, and review a ledger and forward-looking cash runway alongside accounts, cards, debt, budgets, goals, subscriptions, splits, and insights. The README documents these product capabilities; the sampled Android sources show a separate SMS intake path that filters bank alerts, queues them locally, and exposes them to Flutter. Flutter internals beyond the sampled native bridge are represented at subsystem level, so undocumented call relationships are omitted.

Main entry points: [`android/app/src/main/kotlin/com/spendwiser/spendwiser_app/SmsReceiver.kt`](https://github.com/hariharen9/spendwiser-app/blob/main/android/app/src/main/kotlin/com/spendwiser/spendwiser_app/SmsReceiver.kt) (SMS receiver), [`android/app/src/main/kotlin/com/spendwiser/spendwiser_app/MainActivity.kt`](https://github.com/hariharen9/spendwiser-app/blob/main/android/app/src/main/kotlin/com/spendwiser/spendwiser_app/MainActivity.kt) (Flutter SMS channels), [`lib/features/shell/app_shell.dart`](https://github.com/hariharen9/spendwiser-app/blob/main/lib/features/shell/app_shell.dart) (App shell), [`lib/features/home/home_screen.dart`](https://github.com/hariharen9/spendwiser-app/blob/main/lib/features/home/home_screen.dart) (Home and runway)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["App experience"]
  node_app["App entry<br/>[main.dart]"]
  node_shell["App shell<br/>[app_shell.dart]"]
  node_auth["Onboarding and auth<br/>[auth_gate.dart]"]
end

subgraph group_finance["Finance features"]
  node_home["Home and runway<br/>[home_screen.dart]"]
  node_ledger["Ledger<br/>[ledger_screen.dart]"]
  node_finance_modules["Finance modules"]
  node_insights["Insights"]
end

subgraph group_capture["Transaction capture"]
  node_capture_ui["Capture UI"]
  node_capture_parser["Quick capture parser"]
  node_sms_review["SMS review"]
  node_sms_parser["Bank SMS parser"]
end

subgraph group_data["Data and analysis"]
  node_calculator["Finance calculator"]
  node_local_store[("Local persistence")]
  node_cloud_store[("Firestore finance store")]
  node_export["Backup and export"]
end

subgraph group_android["Android SMS bridge"]
  node_sms_receiver["SMS receiver<br/>[SmsReceiver.kt]"]
  node_sms_filter["SMS candidate filter<br/>[SmsFilter.kt]"]
  node_sms_queue[("Pending SMS queue<br/>[SmsInboxStore.kt]")]
  node_sms_events["SMS event bridge<br/>[SmsEventBus.kt]"]
  node_native_channel["Flutter SMS channels<br/>[MainActivity.kt]"]
  node_sms_notice["SMS notification<br/>[SmsNotifier.kt]"]
end

node_user(("Finance user"))

node_user -->|"uses"| node_app
node_app -.->|"opens"| node_shell
node_shell -.->|"gates access"| node_auth
node_shell -.->|"shows home"| node_home
node_user -->|"records spending"| node_capture_ui
node_capture_ui -->|"parses typed input"| node_capture_parser
node_user -->|"reviews alerts"| node_sms_review
node_sms_review -->|"parses bank messages"| node_sms_parser
node_user -->|"reviews transactions"| node_ledger
node_user -->|"checks runway"| node_home
node_home -->|"uses forecasts"| node_calculator
node_user -->|"manages finances"| node_finance_modules
node_user -->|"views analysis"| node_insights
node_user -->|"exports data"| node_export
node_sms_receiver -->|"stores candidate"| node_sms_queue
node_sms_receiver -->|"checks message"| node_sms_filter
node_sms_receiver -->|"emits queued item"| node_sms_events
node_sms_receiver -->|"notifies user"| node_sms_notice
node_native_channel -->|"registers stream"| node_sms_events
node_native_channel -->|"serves queue calls"| node_sms_queue
node_native_channel -->|"runs test notice"| node_sms_notice

click node_app "https://github.com/hariharen9/spendwiser-app/blob/main/lib/main.dart"
click node_shell "https://github.com/hariharen9/spendwiser-app/blob/main/lib/features/shell/app_shell.dart"
click node_auth "https://github.com/hariharen9/spendwiser-app/blob/main/lib/features/auth/auth_gate.dart"
click node_home "https://github.com/hariharen9/spendwiser-app/blob/main/lib/features/home/home_screen.dart"
click node_ledger "https://github.com/hariharen9/spendwiser-app/blob/main/lib/features/ledger/ledger_screen.dart"
click node_finance_modules "https://github.com/hariharen9/spendwiser-app/tree/main/lib/features"
click node_insights "https://github.com/hariharen9/spendwiser-app/blob/main/lib/features/insights/insights_screen.dart"
click node_capture_ui "https://github.com/hariharen9/spendwiser-app/tree/main/lib/features/home/widgets"
click node_capture_parser "https://github.com/hariharen9/spendwiser-app/blob/main/lib/features/home/services/capture_parser.dart"
click node_sms_review "https://github.com/hariharen9/spendwiser-app/blob/main/lib/features/sms/sms_review_sheet.dart"
click node_sms_parser "https://github.com/hariharen9/spendwiser-app/blob/main/lib/data/sms/bank_sms_parser.dart"
click node_calculator "https://github.com/hariharen9/spendwiser-app/blob/main/lib/data/services/finance_calculator.dart"
click node_local_store "https://github.com/hariharen9/spendwiser-app/blob/main/lib/data/persistence/hive_persistence.dart"
click node_cloud_store "https://github.com/hariharen9/spendwiser-app/blob/main/lib/data/firebase/firestore_finance_store.dart"
click node_export "https://github.com/hariharen9/spendwiser-app/blob/main/lib/data/services/backup_service.dart"
click node_sms_receiver "https://github.com/hariharen9/spendwiser-app/blob/main/android/app/src/main/kotlin/com/spendwiser/spendwiser_app/SmsReceiver.kt"
click node_sms_filter "https://github.com/hariharen9/spendwiser-app/blob/main/android/app/src/main/kotlin/com/spendwiser/spendwiser_app/SmsFilter.kt"
click node_sms_queue "https://github.com/hariharen9/spendwiser-app/blob/main/android/app/src/main/kotlin/com/spendwiser/spendwiser_app/SmsInboxStore.kt"
click node_sms_events "https://github.com/hariharen9/spendwiser-app/blob/main/android/app/src/main/kotlin/com/spendwiser/spendwiser_app/SmsEventBus.kt"
click node_native_channel "https://github.com/hariharen9/spendwiser-app/blob/main/android/app/src/main/kotlin/com/spendwiser/spendwiser_app/MainActivity.kt"
click node_sms_notice "https://github.com/hariharen9/spendwiser-app/blob/main/android/app/src/main/kotlin/com/spendwiser/spendwiser_app/SmsNotifier.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,node_shell,node_auth,node_user toneBlue
class node_home,node_ledger,node_finance_modules,node_insights toneAmber
class node_capture_ui,node_capture_parser,node_sms_review,node_sms_parser toneMint
class node_calculator,node_local_store,node_cloud_store,node_export toneRose
class node_sms_receiver,node_sms_filter,node_sms_queue,node_sms_events,node_native_channel,node_sms_notice toneIndigo
```

## Components

### App experience

- [App entry](https://github.com/hariharen9/spendwiser-app/blob/main/lib/main.dart): `lib/main.dart`
- [App shell](https://github.com/hariharen9/spendwiser-app/blob/main/lib/features/shell/app_shell.dart): `lib/features/shell/app_shell.dart`
- [Onboarding and auth](https://github.com/hariharen9/spendwiser-app/blob/main/lib/features/auth/auth_gate.dart): `lib/features/auth/auth_gate.dart`

### Finance features

- [Home and runway](https://github.com/hariharen9/spendwiser-app/blob/main/lib/features/home/home_screen.dart): `lib/features/home/home_screen.dart`
- [Ledger](https://github.com/hariharen9/spendwiser-app/blob/main/lib/features/ledger/ledger_screen.dart): `lib/features/ledger/ledger_screen.dart`
- [Finance modules](https://github.com/hariharen9/spendwiser-app/tree/main/lib/features): `lib/features`
- [Insights](https://github.com/hariharen9/spendwiser-app/blob/main/lib/features/insights/insights_screen.dart): `lib/features/insights/insights_screen.dart`

### Transaction capture

- [Capture UI](https://github.com/hariharen9/spendwiser-app/tree/main/lib/features/home/widgets): `lib/features/home/widgets`
- [Quick capture parser](https://github.com/hariharen9/spendwiser-app/blob/main/lib/features/home/services/capture_parser.dart): `lib/features/home/services/capture_parser.dart`
- [SMS review](https://github.com/hariharen9/spendwiser-app/blob/main/lib/features/sms/sms_review_sheet.dart): `lib/features/sms/sms_review_sheet.dart`
- [Bank SMS parser](https://github.com/hariharen9/spendwiser-app/blob/main/lib/data/sms/bank_sms_parser.dart): `lib/data/sms/bank_sms_parser.dart`

### Data and analysis

- [Finance calculator](https://github.com/hariharen9/spendwiser-app/blob/main/lib/data/services/finance_calculator.dart): `lib/data/services/finance_calculator.dart`
- [Local persistence](https://github.com/hariharen9/spendwiser-app/blob/main/lib/data/persistence/hive_persistence.dart): `lib/data/persistence/hive_persistence.dart`
- [Firestore finance store](https://github.com/hariharen9/spendwiser-app/blob/main/lib/data/firebase/firestore_finance_store.dart): `lib/data/firebase/firestore_finance_store.dart`
- [Backup and export](https://github.com/hariharen9/spendwiser-app/blob/main/lib/data/services/backup_service.dart): `lib/data/services/backup_service.dart`

### Android SMS bridge

- [SMS receiver](https://github.com/hariharen9/spendwiser-app/blob/main/android/app/src/main/kotlin/com/spendwiser/spendwiser_app/SmsReceiver.kt): `android/app/src/main/kotlin/com/spendwiser/spendwiser_app/SmsReceiver.kt`
- [SMS candidate filter](https://github.com/hariharen9/spendwiser-app/blob/main/android/app/src/main/kotlin/com/spendwiser/spendwiser_app/SmsFilter.kt): `android/app/src/main/kotlin/com/spendwiser/spendwiser_app/SmsFilter.kt`
- [Pending SMS queue](https://github.com/hariharen9/spendwiser-app/blob/main/android/app/src/main/kotlin/com/spendwiser/spendwiser_app/SmsInboxStore.kt): `android/app/src/main/kotlin/com/spendwiser/spendwiser_app/SmsInboxStore.kt`
- [SMS event bridge](https://github.com/hariharen9/spendwiser-app/blob/main/android/app/src/main/kotlin/com/spendwiser/spendwiser_app/SmsEventBus.kt): `android/app/src/main/kotlin/com/spendwiser/spendwiser_app/SmsEventBus.kt`
- [Flutter SMS channels](https://github.com/hariharen9/spendwiser-app/blob/main/android/app/src/main/kotlin/com/spendwiser/spendwiser_app/MainActivity.kt): `android/app/src/main/kotlin/com/spendwiser/spendwiser_app/MainActivity.kt`
- [SMS notification](https://github.com/hariharen9/spendwiser-app/blob/main/android/app/src/main/kotlin/com/spendwiser/spendwiser_app/SmsNotifier.kt): `android/app/src/main/kotlin/com/spendwiser/spendwiser_app/SmsNotifier.kt`

### Other components

- **Finance user**

## Connections

- Finance user → App entry: uses (evidence: `README.md`)
- App entry → App shell: opens
- App shell → Onboarding and auth: gates access
- App shell → Home and runway: shows home
- Finance user → Capture UI: records spending (evidence: `README.md`)
- Capture UI → Quick capture parser: parses typed input (evidence: `README.md`)
- Finance user → SMS review: reviews alerts (evidence: `README.md`)
- SMS review → Bank SMS parser: parses bank messages (evidence: `README.md`)
- Finance user → Ledger: reviews transactions (evidence: `README.md`)
- Finance user → Home and runway: checks runway (evidence: `README.md`)
- Home and runway → Finance calculator: uses forecasts (evidence: `README.md`)
- Finance user → Finance modules: manages finances (evidence: `README.md`)
- Finance user → Insights: views analysis (evidence: `README.md`)
- Finance user → Backup and export: exports data (evidence: `README.md`)
- SMS receiver → Pending SMS queue: stores candidate (evidence: `android/app/src/main/kotlin/com/spendwiser/spendwiser_app/SmsReceiver.kt`)
- SMS receiver → SMS candidate filter: checks message (evidence: `android/app/src/main/kotlin/com/spendwiser/spendwiser_app/SmsReceiver.kt`)
- SMS receiver → SMS event bridge: emits queued item (evidence: `android/app/src/main/kotlin/com/spendwiser/spendwiser_app/SmsReceiver.kt`)
- SMS receiver → SMS notification: notifies user (evidence: `android/app/src/main/kotlin/com/spendwiser/spendwiser_app/SmsReceiver.kt`)
- Flutter SMS channels → SMS event bridge: registers stream (evidence: `android/app/src/main/kotlin/com/spendwiser/spendwiser_app/MainActivity.kt`)
- Flutter SMS channels → Pending SMS queue: serves queue calls (evidence: `android/app/src/main/kotlin/com/spendwiser/spendwiser_app/MainActivity.kt`)
- Flutter SMS channels → SMS notification: runs test notice (evidence: `android/app/src/main/kotlin/com/spendwiser/spendwiser_app/MainActivity.kt`)