# cneuralnetwork/kharcha architecture

> Architecture diagram of the GitHub repository cneuralnetwork/kharcha, 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/cneuralnetwork/kharcha
- Repository: https://github.com/cneuralnetwork/kharcha

## Overview

Kharcha is a private spending ledger: users add entries manually or import bank SMS, review parsed transactions, and use the ledger for budgets and insights. On Android, allowlisted inbox messages pass through the native reader and on-device parser; pasted messages use the same parsing flow. The app stores data locally and offers optional encrypted backup to a small API that stores ciphertext in Postgres. The graph reflects README-described flows and SOURCE INDEX references; some screen-level wiring is not shown in the sampled source.

Main entry points: [`mobile/src/state/LedgerProvider.tsx`](https://github.com/cneuralnetwork/kharcha/blob/main/mobile/src/state/LedgerProvider.tsx) (Ledger state), [`mobile/src/app`](https://github.com/cneuralnetwork/kharcha/tree/main/mobile/src/app) (App screens), [`mobile/src/lib/sms.ts`](https://github.com/cneuralnetwork/kharcha/blob/main/mobile/src/lib/sms.ts) (SMS ingestion), [`mobile/src/lib/backup.ts`](https://github.com/cneuralnetwork/kharcha/blob/main/mobile/src/lib/backup.ts) (Backup encryption)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Entry capture"]
  node_screens["App screens"]
  node_smsreader["Android SMS reader"]
  node_smsbridge["SMS module bridge"]
  node_smsflow["SMS ingestion<br/>[sms.ts]"]
  node_parser["SMS parser<br/>[parser.ts]"]
  node_manual["Manual entry<br/>[manual.tsx]"]
  node_import["Paste and review<br/>[import.tsx]"]
end

subgraph group_ledger["Ledger and views"]
  node_ledgerstate["Ledger state<br/>[LedgerProvider.tsx]"]
  node_model["Ledger model<br/>[model.ts]"]
  node_localdb[("Local ledger storage<br/>[database.ts]")]
  node_webdb[("Browser ledger storage<br/>[database.web.ts]")]
  node_views["Budgets and insights"]
end

subgraph group_backup["Encrypted backup"]
  node_backupui["Backup controls<br/>[backup.tsx]"]
  node_backupcrypto["Backup encryption<br/>[backup.ts]"]
end

subgraph group_service["Backup service"]
  node_backupapi["Backup API<br/>[app.ts]"]
  node_store["Postgres store<br/>[store.ts]"]
  node_postgres[("Postgres database")]
  node_apiwiring["API startup<br/>[index.ts]"]
end

node_person(("Ledger user"))

node_person -->|"uses"| node_screens
node_screens -->|"adds entries"| node_manual
node_screens -->|"pastes messages"| node_import
node_screens -->|"starts SMS scan"| node_smsflow
node_smsflow -->|"requests messages"| node_smsbridge
node_smsbridge -->|"calls native reader"| node_smsreader
node_smsflow -->|"parses messages"| node_parser
node_import -->|"parses pasted text"| node_parser
node_parser -->|"offers parsed entry"| node_ledgerstate
node_manual -->|"submits entry"| node_ledgerstate
node_ledgerstate -.->|"updates ledger"| node_localdb
node_ledgerstate -.->|"uses browser storage"| node_webdb
node_localdb -->|"uses types"| node_model
node_webdb -->|"uses types"| node_model
node_ledgerstate -.->|"serves ledger data"| node_views
node_person -->|"opts into backup"| node_backupui
node_backupui -->|"backs up or restores"| node_backupcrypto
node_backupcrypto -->|"exports snapshot"| node_localdb
node_backupcrypto -->|"sends ciphertext"| node_backupapi
node_apiwiring -->|"configures routes"| node_backupapi
node_apiwiring -->|"initializes store"| node_store
node_backupapi -->|"reads and writes"| node_store
node_store -->|"queries"| node_postgres

click node_screens "https://github.com/cneuralnetwork/kharcha/tree/main/mobile/src/app"
click node_smsreader "https://github.com/cneuralnetwork/kharcha/blob/main/mobile/modules/kharcha-sms/android/src/main/java/dev/kharcha/sms/KharchaSmsModule.kt"
click node_smsbridge "https://github.com/cneuralnetwork/kharcha/blob/main/mobile/modules/kharcha-sms/src/KharchaSmsModule.ts"
click node_smsflow "https://github.com/cneuralnetwork/kharcha/blob/main/mobile/src/lib/sms.ts"
click node_parser "https://github.com/cneuralnetwork/kharcha/blob/main/mobile/src/lib/parser.ts"
click node_manual "https://github.com/cneuralnetwork/kharcha/blob/main/mobile/src/app/manual.tsx"
click node_import "https://github.com/cneuralnetwork/kharcha/blob/main/mobile/src/app/import.tsx"
click node_ledgerstate "https://github.com/cneuralnetwork/kharcha/blob/main/mobile/src/state/LedgerProvider.tsx"
click node_model "https://github.com/cneuralnetwork/kharcha/blob/main/mobile/src/lib/model.ts"
click node_localdb "https://github.com/cneuralnetwork/kharcha/blob/main/mobile/src/lib/database.ts"
click node_webdb "https://github.com/cneuralnetwork/kharcha/blob/main/mobile/src/lib/database.web.ts"
click node_views "https://github.com/cneuralnetwork/kharcha/tree/main/mobile/src/app/(tabs)"
click node_backupui "https://github.com/cneuralnetwork/kharcha/blob/main/mobile/src/app/backup.tsx"
click node_backupcrypto "https://github.com/cneuralnetwork/kharcha/blob/main/mobile/src/lib/backup.ts"
click node_backupapi "https://github.com/cneuralnetwork/kharcha/blob/main/api/src/app.ts"
click node_store "https://github.com/cneuralnetwork/kharcha/blob/main/api/src/store.ts"
click node_apiwiring "https://github.com/cneuralnetwork/kharcha/blob/main/api/src/index.ts"

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_screens,node_smsreader,node_smsbridge,node_smsflow,node_parser,node_manual,node_import,node_person toneBlue
class node_ledgerstate,node_model,node_localdb,node_webdb,node_views toneAmber
class node_backupui,node_backupcrypto toneMint
class node_backupapi,node_store,node_postgres,node_apiwiring toneRose
```

## Components

### Entry capture

- [App screens](https://github.com/cneuralnetwork/kharcha/tree/main/mobile/src/app): `mobile/src/app`
- [Android SMS reader](https://github.com/cneuralnetwork/kharcha/blob/main/mobile/modules/kharcha-sms/android/src/main/java/dev/kharcha/sms/KharchaSmsModule.kt): `mobile/modules/kharcha-sms/android/src/main/java/dev/kharcha/sms/KharchaSmsModule.kt`
- [SMS module bridge](https://github.com/cneuralnetwork/kharcha/blob/main/mobile/modules/kharcha-sms/src/KharchaSmsModule.ts): `mobile/modules/kharcha-sms/src/KharchaSmsModule.ts`
- [SMS ingestion](https://github.com/cneuralnetwork/kharcha/blob/main/mobile/src/lib/sms.ts): `mobile/src/lib/sms.ts`
- [SMS parser](https://github.com/cneuralnetwork/kharcha/blob/main/mobile/src/lib/parser.ts): `mobile/src/lib/parser.ts`
- [Manual entry](https://github.com/cneuralnetwork/kharcha/blob/main/mobile/src/app/manual.tsx): `mobile/src/app/manual.tsx`
- [Paste and review](https://github.com/cneuralnetwork/kharcha/blob/main/mobile/src/app/import.tsx): `mobile/src/app/import.tsx`

### Ledger and views

- [Ledger state](https://github.com/cneuralnetwork/kharcha/blob/main/mobile/src/state/LedgerProvider.tsx): `mobile/src/state/LedgerProvider.tsx`
- [Ledger model](https://github.com/cneuralnetwork/kharcha/blob/main/mobile/src/lib/model.ts): `mobile/src/lib/model.ts`
- [Local ledger storage](https://github.com/cneuralnetwork/kharcha/blob/main/mobile/src/lib/database.ts): `mobile/src/lib/database.ts`
- [Browser ledger storage](https://github.com/cneuralnetwork/kharcha/blob/main/mobile/src/lib/database.web.ts): `mobile/src/lib/database.web.ts`
- [Budgets and insights](https://github.com/cneuralnetwork/kharcha/tree/main/mobile/src/app/(tabs)): `mobile/src/app/(tabs)`

### Encrypted backup

- [Backup controls](https://github.com/cneuralnetwork/kharcha/blob/main/mobile/src/app/backup.tsx): `mobile/src/app/backup.tsx`
- [Backup encryption](https://github.com/cneuralnetwork/kharcha/blob/main/mobile/src/lib/backup.ts): `mobile/src/lib/backup.ts`

### Backup service

- [Backup API](https://github.com/cneuralnetwork/kharcha/blob/main/api/src/app.ts): `api/src/app.ts`
- [Postgres store](https://github.com/cneuralnetwork/kharcha/blob/main/api/src/store.ts): `api/src/store.ts`
- **Postgres database**
- [API startup](https://github.com/cneuralnetwork/kharcha/blob/main/api/src/index.ts): `api/src/index.ts`

### Other components

- **Ledger user**

## Connections

- Ledger user → App screens: uses (evidence: `README.md`)
- App screens → Manual entry: adds entries (evidence: `README.md`)
- App screens → Paste and review: pastes messages (evidence: `README.md`)
- App screens → SMS ingestion: starts SMS scan (evidence: `README.md`)
- SMS ingestion → SMS module bridge: requests messages (evidence: `mobile/src/lib/sms.ts`)
- SMS module bridge → Android SMS reader: calls native reader (evidence: `README.md`)
- SMS ingestion → SMS parser: parses messages (evidence: `mobile/src/lib/sms.ts`)
- Paste and review → SMS parser: parses pasted text (evidence: `README.md`)
- SMS parser → Ledger state: offers parsed entry (evidence: `README.md`)
- Manual entry → Ledger state: submits entry (evidence: `README.md`)
- Ledger state → Local ledger storage: updates ledger
- Ledger state → Browser ledger storage: uses browser storage (evidence: `README.md`)
- Local ledger storage → Ledger model: uses types (evidence: `mobile/src/lib/database.ts`)
- Browser ledger storage → Ledger model: uses types (evidence: `mobile/src/lib/database.web.ts`)
- Ledger state → Budgets and insights: serves ledger data
- Ledger user → Backup controls: opts into backup (evidence: `README.md`)
- Backup controls → Backup encryption: backs up or restores (evidence: `README.md`)
- Backup encryption → Local ledger storage: exports snapshot (evidence: `mobile/src/lib/backup.ts`)
- Backup encryption → Backup API: sends ciphertext (evidence: `README.md`)
- API startup → Backup API: configures routes (evidence: `api/src/index.ts`)
- API startup → Postgres store: initializes store (evidence: `api/src/index.ts`)
- Backup API → Postgres store: reads and writes (evidence: `api/src/app.ts`)
- Postgres store → Postgres database: queries (evidence: `api/src/store.ts`)
