Bupples

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.

Money is integer minor units end to end. Parsing does string-based integer arithmetic and never touches a float, 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.

• 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

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.

The invariants are asserted in tests: 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.

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.

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.

• 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

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.

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.

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.

Both implementations work in integer minor units and use exact rational arithmetic over big integers, so rounding is deterministic in both runtimes. 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.

• 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

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.

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.

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.

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.

• 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

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; the rules stay strict.

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.

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.

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.

• 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

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 on the same model.

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.

A purchase state the client reports is a purchase state the client can be persuaded to lie about, and the paid cosmetics are the visible reward, so they are the obvious target. The rules deny a client-written frame id outright; the only route onto one is a callable that reads the live entitlement document first. The webhook is authenticated with a shared secret held in Secret Manager. Scheduled jobs then handle the parts a purchase SDK does not: lapse enforcement, expiring perks, grace status, trial reminders and gifting between subscribers.

Entitlement changes take a network round trip and depend on a webhook being reachable, so a subscriber who upgrades in a tunnel sees their perks a moment after the server hears about it.

Widgets need platform-specific rendering and receipt scanning benefits from on-device recognition. The current build accepts the dependency work that comes with that: simulator compatibility is handled explicitly, and device binaries are checked again after archiving.

Platform-specific build configuration, native integration tests and separate device-artefact verification.

The app was built in Malaysia and its first bills were in ringgit, which is precisely how a currency becomes a hardcoded fallback and a group in Singapore ends up looking at RM. Region resolution has a documented provenance ladder, currency and cash-rounding behaviour are per-currency tables, and the standing rule forbids hardcoding the local currency as a fallback in new code. Multi-currency then falls out of the same discipline: each currency is its own independent ledger and nothing is ever converted, because a wrong exchange rate inside a shared bill is worse than no exchange rate at all.

Every money surface has to carry a currency and know its exponent, and the display contract now has four hand-maintained mirrors (the Dart formatter, the Cloud Functions copy, the iOS widget and the Android widget provider), which have to change together.

An offset is only correct until daylight saving moves. A London account that reported +0 in February had its nine o’clock reminder land at ten for the whole of March. A zone name resolves the exact local hour on Node, which has full ICU data, at the moment the job runs.

A platform dependency on the client purely to read the zone name, and a set of DST-boundary tests that have to be kept honest.

The current source exports 119 handlers. Naming the functions in each deployment limits its scope and makes the intended production change reviewable. Build-freshness, signing and deployment checks sit in release scripts and runbooks.

Long deploy commands, and a new function has to be named explicitly or it silently never ships. The checklist trades a loud failure for a quiet one, so the runbook has to list the order.