Expense Tracker – Automated Financial Ledger for Nepal

Expense Tracker is a privacy-first, fully automated personal finance engine built specifically around the realities of Nepal’s banking ecosystem (eSewa, Nabil Bank, and Laxmi Sunrise). It continuously monitors transaction emails and bank SMS messages, reconciles them into an immutable ledger, and visualizes spending patterns—requiring zero manual entries, no hosted server, and zero raw email content ever leaving the user’s laptop.

🎯 The Problem

Most personal finance apps either demand exhausting manual data entry or require handing over full email inbox access to third-party cloud servers. Furthermore, standard financial tools struggle with Nepal’s multi-channel notification quirks:

• Banks like Nabil often notify of a single transaction across both email and SMS, leading naive systems to double-count expenses.
• Internal account-to-account transfers (e.g., funding an eSewa digital wallet from a bank account) are falsely registered as new expenditures.
• Floating-point financial calculations introduce round-off errors and ledger drift.

💡 Solution & Core Invariants

The project strictly adheres to five core system invariants:

• Money is integer paisa: All amounts are strictly modeled as integer paisa, completely eliminating floating-point rounding inaccuracies.
• Two transports, one transaction: Cross-channel notifications for the same transaction (SMS + email) automatically collapse onto a single normalized transaction row in PostgreSQL via unique constraints.
• Transfers are not expenses: Movements of funds between personal accounts net to zero, preventing distorted spend totals.
• Offline LLM Categorization: Merchant categorization is powered locally using Ollama running private models on the user’s laptop, ensuring merchant analysis occurs without cloud telemetry.
• Zero data leakage: Raw .eml contents and email credentials stay strictly local; Supabase only receives normalized ledger rows protected by Row Level Security.
• Idempotency & Balance Reconciliation: Pipeline runs can be safely executed repeatedly over any time window without producing duplicates. Unreconciled balance steps surface as explicit ledger_gaps rather than silently falsified totals.

🛠️ Architecture & Pipeline

  ┌─────────────┐   IMAP    ┌──────────────────────┐   rows    ┌──────────┐
  │    Gmail    │──────────▶│   Local batch worker │──────────▶│ Supabase │
  └─────────────┘           │   (your laptop)      │           │ (ledger) │
                            │                      │           └─────┬────┘
  ┌─────────────┐  staged   │  parse · dedupe      │                 │ reads
  │  Bank SMS   │──────────▶│  match transfers     │                 ▼
  │  (phone)    │           │  reconcile · label   │           ┌──────────┐
  └─────────────┘           └──────────────────────┘           │  Flutter │
                                                               │   app    │
                                                               └──────────┘

• Local Batch Worker: Python CLI with modular parsers for eSewa, Nabil Bank, and Laxmi Sunrise, backed by an offline test corpus with 150+ unit tests.
• Database & Ledger: Supabase PostgreSQL with RLS, audit logs, and aggregate views.
• Mobile Client: Flutter companion app reading normalized balances and spending breakdowns directly from Supabase.

View Source on GitHub