Bupples

Why it was hard

A split is a division that rarely comes out even. Three people on a ten-ringgit bill, four on a bill ending in a stray cent, percentage splits, share-weighted splits, a bill two people paid at once. Every one produces a remainder, and every feature that handled its own remainder was a chance for the expense screen and the balance screen to disagree by a cent — and for a group's balances to stop summing to zero. Parsing was its own hazard before any division happened: multiplying a decimal by a hundred and rounding drifts in binary floating point, which turns 0.35 into 34 cents and 12.005 into 1200.

Options considered

• Store amounts as doubles and round when displaying them — the obvious version, and the one whose specific failures are written into the file as the reason it was abandoned
• Let each feature round its own way, which is what produces the two-screens-disagree bug
• Integer minor units everywhere, with one shared kernel that every split calls

What I built

Money is integer minor units end to end. Parsing does string-based integer arithmetic rather than touching a float at all, and is exponent-aware for currencies with zero, two or three decimal places. One file is the only place cents are distributed: a proportional distributor that gives leftover cents to the largest weights first, and an even splitter that gives them to the first sorted ids. Its own header says why it exists — one implementation shared by the expense split, the multi-payer who-paid editor and the settlement surplus maths, so no two call sites can drift. Expense shares return cents per participant for equal, exact, percentage and share methods and always sum back to the total; custom splits with some members pinned use largest-remainder rounding for the rest. Currencies are never added together: the ledger is keyed by currency and within each one the members' balances sum to zero.

What it cost

A shared kernel means no feature gets to invent a local rounding rule for the sake of a nicer-looking number. And the money format contract is not automatically shared across runtimes — it has hand-maintained mirrors in the Cloud Functions copy, the iOS widget and the Android widget provider, so a change to one has to land in all four.

How I know it works

The invariants are asserted rather than assumed: shares always sum to the expense total, and within each currency the members' net balances sum to zero. The rule is written into the repository's standing rules as law, so a later feature cannot quietly reintroduce a float on an amount.

Why it was hard

There are two ledgers, not one. The direct ledger says who owes whom. The simplified plan solves for the fewest transfers — at most one less than the number of people — and to do that it reroutes money: it asks A to pay C when A never owed C, because A owed B and B owed C. When someone recorded a payment against a rerouted row, the ledger went looking for a direct A-to-C debt, found none, clamped the reduction to zero, and the payment simply disappeared. Both sides still showed the debt and the payer was invited to pay it again. It is the worst class of bug an expense app can have, because the app keeps insisting and the user knows they already paid.

Options considered

• Delete the fewest-payments plan and show only direct debts — which loses the feature that makes settling a six-person trip bearable
• Record the routed payment as a direct credit from payer to receiver — which invents a debt that never existed and breaks the zero-sum
• Decompose the routed payment into a flow through the debt graph at the moment it is recorded, and store the edges it covers on the payment itself

What I built

The third. When a payment is recorded against a rerouted row, it is decomposed into a flow through the owes graph and the covered edges are stored on the request; the ledger then reduces each of those real edges instead of hunting for a pair that does not exist. The soundness argument is per-node conservation: in a flow, every intermediate node's inflow equals its outflow, so only the payer's and the receiver's net positions move and nobody else's balance is touched. The existing per-edge clamp still applies on top, which bounds the failure mode — a stale or hostile decomposition can only ever under-apply, never manufacture a credit. The ledger validates the stored flow before trusting it and falls back to the old direct clamp if validation fails. The server keeps its own copy of the same computation, with a comment requiring the two apply loops stay line-for-line comparable.

What it cost

The payment record now carries derived data that can go stale if the underlying bills are edited afterwards. That is bounded rather than solved: validation plus the per-edge clamp means a stale decomposition under-applies and the balance stays owed — recoverable — instead of over-applying, which is not. It also adds a second implementation of the same arithmetic to keep in step.

How I know it works

A dedicated backend unit test covers the routed case. Under the repository's standing test doctrine, a behavioural fix does not count until its test has been verified red against the pre-fix code by reverting the fix and re-running it.

Why it was hard

When a table splits a scanned receipt, each person taps the items they had and sees their share update immediately. The preview is computed on the phone in Dart; the money is written by a Cloud Function in TypeScript. Two implementations of the same arithmetic in two runtimes, and if they disagree by one unit the receipt shows one number and the ledger stores another. The arithmetic itself is not simple either: tax and service charge have to ride per item so an item only carries its own proportional slice, items can be claimed by more people than ordered them, some items are claimed by nobody and have to stay in a pot, and real bills do not add up — Malaysia retired the one sen coin, so a cash total rounds to the nearest five sen and prints the adjustment, or on plenty of tills does not print it at all.

Options considered

• Compute everything server-side and drop the live preview — which means tapping an item and waiting for a round trip
• Use floating-point percentages and reconcile with a tolerance at the end — a general fuzz factor is exactly how a real thirty-sen error gets absorbed and shipped as truth
• Exact rational arithmetic over integers, implemented twice against one written contract, with the same invariants written down once and property-tested on the Dart side, with a deterministic pseudo-random sweep over the tax-and-service allocation on the TypeScript side

What I built

Both implementations work in integer minor units and use exact rational arithmetic over big integers, so rounding is deterministic in both runtimes rather than dependent on either one's float behaviour. The invariants are named in both files and hold for any input: member subtotals plus the unclaimed pot equal the item total exactly, with over-claims clamped first; tax and service allocated per member plus the unallocated remainder equal tax plus service exactly; splitting the remainder equally conserves the pot exactly. Cash rounding is a per-currency table of named steps rather than a tolerance, and the reconciler's stated design rule is that tolerances are named, bounded and enumerated — anything the checks cannot explain comes out as an explicit residual for a human to resolve, never as a silent adjustment.

What it cost

Roughly sixteen hundred lines of the same arithmetic exist twice and must change together. Nothing in the toolchain enforces that; only the tests, the shared invariant list and a comment at the top of each file do.

How I know it works

The same invariants written down once and property-tested on the Dart side, with a deterministic pseudo-random sweep over the tax-and-service allocation on the TypeScript side, plus targeted unit tests for reconciliation and handwritten tip inference.

Why it was hard

Every figure in the app derives from documents that phones write. The natural Firestore shape lets a member edit their own membership row — and since money is keyed to membership, editing membership edits money. Session ids that can be listed leak private groups. And the operations that matter arrive over mobile networks where a retry, a double tap or a resumed background write is normal, so an operation that applies twice is not a rare case to design against later.

Options considered

• Trust the client and reconcile afterwards — an expense app cannot reconcile a hostile write after the fact
• Route every write through Cloud Functions — which gives up the realtime listeners that make shared balances feel live
• Rules that bind every write to the caller's uid, plus server-only fields clients cannot touch at all, plus idempotent callables for the operations that must not double-apply

What I built

The third, drawn as an explicit boundary. Authorisation binds to the Firebase auth uid and never to a client-supplied member id. Sessions cannot be listed — a session is readable only through an unguessable id reached via a join-code lookup. Joining goes through a Cloud Function using the Admin SDK, so a client can never grow the authorised-uid list itself; a subset guard prevents the self-leave branch being used to evict the host or swap in another uid. Expenses are owner-scoped: the creator or the host may edit, and everyone else files a change request. The host field is server-only, and ownership moves only through a callable so the hand-off is audited and notified. Paid cosmetic frames are denied to clients outright in the rules; the only route onto one is a callable that re-reads the live entitlement first. On the server, transactions carry the write-critical paths and idempotency is committed inside the transaction rather than checked before it — a double-tapped claim returns an 'already done' result instead of applying twice.

What it cost

The rules file is a second description of the domain's shape. Add a field to an expense and it has to be added to the rules' payload validator too, or the write is rejected in production and nowhere else. That cost is paid down with an emulator suite rather than with looser rules.

How I know it works

The current tree contains 29 Firestore rules test files and 64 backend unit test files. The build 184 verification record reports 456 rules checks and 803 backend unit checks passed. The July security audit remains a historical record, not a fresh security certification.

Why it was hard

A photographed receipt is skewed, creased, thermally faded, often bilingual, and sometimes has a tip written on it in pen. One model call at maximum quality reads it well and costs money and seconds on every single scan, including the clean ones. A cheap call is fast and wrong exactly where it matters — the line with the price on it. And a progress indicator that sits still for eight seconds reads as a broken app, whatever it is doing underneath.

Options considered

• Cloud extraction on every scan at full quality — slow first frame, and a per-scan bill on a free app
• On-device OCR only — it gives text and boxes, but not structure: which line is an item, which is service charge, which is the total
• Two tiers with a confidence gate, and an on-device pass in front of both so progress is real

What I built

ML Kit provides an on-device text pass before the cloud extraction completes. A fast Gemini pass structures the receipt; confidence and arithmetic checks decide whether uncertain lines need another pass with a thinking budget and more focused image context. Both tiers currently use Gemini 2.5 Flash. The result is reconciled against the printed total, then shown in an editable review that keeps inclusive taxes, extra charges and discounts distinct. Inconclusive discount interpretations ask for a human check rather than silently changing the amount.

What it cost

Two prompt paths and two failure paths to maintain. And the accurate tier currently points at the same model as the fast one, pending a stronger one being provisioned, so today the second pass buys thinking budget and a zoomed crop rather than a larger model.

How I know it works

Extraction is not trusted on its own: the lines land in the reconciler, which checks the line arithmetic against the printed totals and refuses to absorb an unexplained difference. Scanning is also behind a Remote Config flag, so it can be switched off in production without shipping a build.