Concepts

These are the domain rules the app is built around. They live as pure functions in src/domain/ and are unit-tested with no mocks.

Money

All monetary values are stored as integer paise (1 rupee = 100 paise) to avoid floating-point drift. Display uses the rupee sign with Indian digit grouping, e.g. ₹1,00,000.00.

Budget and limits

• Monthly budget: a single shared pot the owner sets at the start of the month.
• Daily limit: monthly budget / days in that month.
• Weekly limit: daily limit × that week's days inside the month. Weeks run Monday to Sunday, so the first and last weeks of a month are usually partial and pro-rated automatically. The weekly limits always sum back to the monthly budget.

Rollover

• Daily: hard reset. Unspent amount does not carry to the next day.
• Weekly: carries forward. Unspent weekly budget is added to the next week's available amount. Overspend carries too (a negative carry reduces the next week), but carry never crosses a month boundary - each month starts fresh.

Members and roles

• The owner sets up the household and funds the pot.
• Exactly one member is the finance manager, who holds and spends from the pot. The role is reassignable; attribution stays by member, never by role.
• Members join via an invite code (anonymous auth). A name-only profile is for someone with no phone - others log spends for them.

Settlement (pot + refund out-of-pocket)

• Spends marked paid from pot need no settlement.
• Spends marked own pocket by a non-manager member are fronted personally, so at week-end the finance manager refunds them.
• The manager's own out-of-pocket nets against the pot (no self-refund).

Outside the budget

Two trackers live alongside the budget but never affect it, its limits, or settlement:

• Meal card: a prepaid-card ledger (src/domain/card/). Balance carries over month to month; spends use paid_from='card' and are excluded from budget totals.
• Bills: an optional, self-contained record of non-budget spends (rent, utilities, recharges) with its own categories and history.

For the full product specification, see the Product Requirements.