Hisab - حساب

Split expenses. Settle cleanly. Work offline.
Shared trips, household costs, and personal budgets — with balances that stay clear
when everyone chips in. Flutter · offline-first · optional cloud sync.

Open the web app · Latest release · Documentation

What you get · Screenshots · Install · Develop · Docs · العربية

The name Hisab comes from Arabic حساب (ḥisāb): account / reckoning — settling who owes whom.

---

What you get

Groups & people	Trips, events, or household lists — with participants linked to real accounts when online.
Expenses	Multi-currency amounts, categories, receipts, equally / shares / exact-amount splits, transfers.
Balance & settle-up	Who owes whom, minimal settlement suggestions, record payments in one tap.
Profile	Cross-group dashboard: net balances, KPIs, personal budgets, and an in-app activity feed (online).
Personal lists	Solo budgets and spending (no split UI); optional Android notification scanner drafts.
Offline-first	Full local SQLite. Sync, invites, and members when a backend is attached.
Locales	English and Arabic (RTL), themes, and subtle accent controls.

Modes

Mode	Data	Extra
Local-only (default)	Device SQLite	Everything except sign-in & cross-device sync
Online	Cloud backend + local cache	Invites, members, push, multi-device

Temporarily offline in online mode: expense writes queue and sync later. Invites and member admin need a connection.

---

Screenshots

Onboarding

_{Welcome · Connection (local-only)}

Groups & expenses

_{Groups · Add expense · Settlement}

Demo

_{Onboarding · Open a group, add an expense, settle}

Dark theme

_{Welcome · Connection · Groups · Add expense · Settlement}

---

Two builds

Hisab is open core. This repository is the whole client, and it builds a complete offline app with no backend at all. The hosted sync service that powers invites, shared groups and multi-device is a separate proprietary project, and it plugs in behind an interface that lives here in packages/hisab_backend.

	FOSS	Cloud
Built from	this repository, alone	this repository + a private backend package
Backend	none	hosted Supabase
Application id	com.shenepoy.hisab.foss	com.shenepoy.hisab
Groups, expenses, balances, settle-up, budgets, receipts	yes	yes
Sign-in, invites, shared groups, push, multi-device	no	yes
Licence	AGPL-3.0	AGPL-3.0 client, proprietary backend

Both are published on the same releases page, and they install side by side, so trying one does not overwrite the other.

You are not limited to those two. The backend is an interface, not a vendor: implement it against your own server and you get a third build that is yours end to end. docs/SELF_HOSTING.md is the specification, and docs/BACKEND_BEHAVIOUR.md documents the server-side behaviour the client expects.

---

Install

Web / PWA

Live at hisab.shenepoy.com (Firebase Hosting) — this is the cloud build.
Install from the in-app banner when offered (Chromium Android uses the native install prompt; iPhone/iPad and other mobile browsers get Add-to-Home-Screen steps). On iOS, open the Home Screen app for web push. Works offline after install.

Android

Option
Obtainium (recommended)	— tracks GitHub Releases
APK, cloud build	cloud-<abi>-release.apk from the latest release
APK, FOSS build	app-<abi>-foss-release.apk from the same release — offline only, built entirely from this repository
Play Store	Listing (WIP / when published)

Pick arm64-v8a unless you know your device is older.

---

Develop

Requirements: Flutter / Dart ^3.11

flutter pub get
dart run build_runner build --delete-conflicting-outputs
flutter run

That is the whole setup. There is no backend to configure, no keys to obtain, and no --dart-define to pass — the checked-in packages/hisab_cloud is a no-op stub, so the app runs local-only and every feature that does not inherently need a server works.

Web: generate WASM once if needed:

flutter pub run powersync:setup_web

Android: the foss flavor is the offline one and the default for development:

flutter run --flavor foss

Attaching a backend

Implement the CloudBackend contract in a package of your own and point pubspec_overrides.yaml at it:

dependency_overrides:
  hisab_cloud:
    path: ../my_hisab_cloud

The app calls registerHisabCloud() at startup; if your implementation registers a backend, sign-in, sync, invites and push light up, and if it does not, the app stays local-only. Nothing else in lib/ changes.

Full walkthrough: docs/SELF_HOSTING.md · contract reference: packages/hisab_backend/README.md · server-side expectations: docs/BACKEND_BEHAVIOUR.md

Quick fixes

Issue	Fix
Stays local-only	Expected without a backend package — see Attaching a backend
SQLite crash on web	flutter pub run powersync:setup_web
Android build cannot find a flavor	Pass --flavor foss (or cloud if you supply a backend)
Riverpod / codegen errors after a pull	dart run build_runner build --delete-conflicting-outputs

---

Architecture (short)

• UI / state — Flutter, Riverpod 3 (codegen), GoRouter
• Local DB — SQLite via PowerSync package (always on)
• Cloud — Optional, behind the CloudBackend contract; absent by default
• Sync — Online writes go to the backend then the cache; reads always come from SQLite; a pending queue drains when connectivity returns
• Domain — Groups, participants, expenses (cents), balances, settlements, invites

Deeper map: docs/CODEBASE.md

---

Docs

Guide
Documentation index	All topics
Self-hosting	Implement the contract against your own server
Backend behaviour	Server-side rules the client relies on
Backend contract	Facet-by-facet API reference
Configuration	Build-time flags, online vs local
Security	Public-repo secret policy (what never to commit)
Contributing	Workflow and the CLA
Tests	Unit, widget, integration

---

Testing

flutter test
bash scripts/run_release_checks.sh

CI runs the checks, the test suite and an offline build guard that asserts this tree still builds with no backend attached (.github/workflows/ci.yml). Tagging v* builds and publishes the signed FOSS APKs (.github/workflows/release.yml). No production credentials exist in this repository or in its Actions secrets.

---

Contributing

Pull requests are welcome, and all of them need a CLA — the project can only ship an AGPL client alongside a proprietary backend while one party holds the copyright. CONTRIBUTING.md explains it in one paragraph.

This repository is public. Never commit real keys, service-account JSON, or filled define/env files. See SECURITY.md.

---

License

AGPL-3.0 — use, study, modify and redistribute freely; if you run a modified version as a network service, its users are entitled to your source.

The name Hisab, the Arabic wordmark حساب and the logo are not covered by that licence. Fork away, but please ship your fork under a different name and icon. The hosted backend is a separate proprietary work and is not in this repository — docs/SELF_HOSTING.md is the published specification for building your own.