hisaab

I wanted to know two things from my bank statement: where my money actually goes, and when my zakat falls due. The bank export answers neither at a glance, so I built this.

hisaab (ހިސާބު — "account / reckoning") reads a Maldives Islamic Bank CSV export and turns it into something you can actually read: wealth over time, spending broken down, and a nisab/hawl tracker that tells you when zakat is owed. The statement is parsed in the browser — it never leaves your machine and nothing is uploaded, which felt non-negotiable for a bank statement.

AI-assisted, human-directed. A planning aid, not a fatwa — zakat rulings differ, so check yours with someone qualified.

What it does

• Overview — wealth over time, money-in vs money-out by day/week/month, and the headline numbers (net change, in, out, current wealth) for whatever date range you scope to.
• Spending — where it went, by category and by counterparty, plus your largest single outflows. Internal transfers are shown but called out as moving money, not spending.
• Zakat — tracks your total wealth (bank balance + cash you add) against the nisab, finds when you crossed it, resets the clock whenever you dip below, and reports the next due date and 2.5% amount using the Umm al-Qura Hijri calendar.

Cash on hand is modelled as dated entries: each has its own amount, currency, MVR rate and a held-from/held-until window — so cash you only had for part of the period is counted only while you actually held it, and can legitimately start or break a hawl.

How the zakat rule is applied

1. A daily wealth series is reconstructed from the running balance (ordered by the timestamp embedded in each transaction's description), plus any cash active that day.
2. The hawl starts the first day wealth reaches the nisab.
3. Any day below the nisab resets it; it restarts when wealth next crosses above.
4. After one continuous Hijri year above the threshold, 2.5% is due on the wealth held that day, recurring each Hijri year while you stay above it.

Running it

bun install
bun run dev        # http://localhost:5173
bun run build      # static site in dist/
bun run test       # unit tests for the Hijri + zakat logic

Click Try the sample for synthetic data, or drop in your own export. Regenerate the demo data with bun scripts/gen-sample.ts.

How it's put together

Vite + TypeScript, no UI framework, ECharts for the charts. The logic is split so the parts that matter are testable on their own:

Module	Responsibility
src/parse.ts	CSV → chronologically ordered transactions
src/series.ts	Daily balance + wealth (with dated cash lots)
src/hijri.ts	Umm al-Qura conversion via the built-in Intl calendar
src/zakat.ts	Nisab / hawl engine
src/analytics.ts	Period flows, category & counterparty breakdowns
src/charts.ts, src/views.ts, src/main.ts	Charts, panels, and wiring

Notes

• Built for MIB exports with columns POSTED DATE, VALUE DATE, TRANSACTION TYPE, REFERENCE, DESCRIPTION, AMOUNT, RUNNING BALANCE. Statement amounts are MVR; other currencies are added as cash entries at a rate you set.
• Real statements are never committed (see .gitignore); only a synthetic sample is tracked.