Shared Bill Splitter

I built Shared Bill Splitter, a TypeScript project on @Sidd-ctrl’s GitHub, to manage shared-home bills: create a home, add its members, split bills so the paise add up, and let each member pay their own share. The project started and was last updated in 2026-11, and reports 24 passing tests. It is also listed on my github profile.

• I can create a home and add members; the order in which I add them is stored and reused for bill splits.

I represent money as whole-paise integers: 100 paise equals ₹1. Member addition order is preserved for splitting, and the split is designed not to lose a paisa. Payments use an Idempotency-Key for a single share.

• API: Hono on Cloudflare Workers, with Cloudflare D1 (SQLite) bound as DB.

To run the project locally, I need Node.js 22 or newer (Wrangler 4 needs it) and pnpm 9 or newer. I can enable pnpm with Corepack or install it globally, then install dependencies and start both apps from the repository root:

corepack enable pnpm
# Alternatively:
npm install -g pnpm

pnpm install
pnpm dev

pnpm dev applies the SQL migrations in api/migrations to a local D1 database before the API starts, so the first run needs no extra setup. The API runs at http://localhost:8787 and the web app at http://localhost:5173; I open http://localhost:5173.

pnpm test        # visible tests in api/test, in the Workers runtime
pnpm check       # Biome format + lint
pnpm check:fix   # apply Biome's fixes
pnpm typecheck   # tsc on api and web
pnpm build       # production build of the web app

# Apply migrations again after adding a file to api/migrations
pnpm --filter bill-splitter-api exec wrangler d1 migrations apply DB --local

# Regenerate Env types after editing api/wrangler.jsonc
pnpm --filter bill-splitter-api cf-typegen

The local database lives in api/.wrangler; deleting that folder starts from an empty home. The initial schema and named constraints are in api/migrations/0001_init.sql. The API entry point and JSON 404/500 handlers are in api/src/index.ts; home, member, balance, and home-detail routes are in api/src/routes/homes.ts, while bill creation, listing, and share payments are in api/src/routes/bills.ts. SQL storage is split between api/src/store/homes.ts and api/src/store/bills.ts; the pure split function is in api/src/split.ts, with input parsing and HTTP helpers in api/src/validation.ts and api/src/http.ts.

The single-page web route is web/src/routes/index.tsx. Its components live in web/src/components/, data-loading hooks in web/src/hooks/, and the typed API client with timeout and error handling is web/src/api.ts. Paise formatting and rupee input parsing are in web/src/format.ts; the dark and gold theme is in web/src/styles.css.

• Web: React, Vite, and TanStack Router; the frontend and API are both TypeScript, with no any.
• Tests run with Vitest inside the Workers runtime. Biome handles formatting and linting; pnpm check runs those checks, and type checking uses tsc --noEmit.
• The repository is a pnpm workspace.
• I can create a bill, split it across every member without losing a paisa, pay an individual share with an Idempotency-Key, and read what each member still owes.

The API creates homes, members, and bills, and exposes balances. POST /api/homes returns 201 { id, name } and rejects a missing or blank name with 422; POST /api/homes/:homeId/members returns 201 { id, homeId, name } and returns 404 if the home does not exist. Creating a bill at POST /api/homes/:homeId/bills returns 201 { id, homeId, title, totalCents, shares[] }; a missing home returns 404, while a bad amount or a home with no members returns 422. POST /api/bills/:billId/shares/:shareId/pay returns 200 { id, memberId, amountCents, paidAt }; balances come from GET /api/homes/:homeId/balances, returning 200 { balances: [{ memberId, name, outstandingCents }] }. Every error response is JSON in the form { "error": "message" }.

The web page also uses read-only GET /api/homes, GET /api/homes/:homeId, and GET /api/homes/:homeId/bills endpoints; these support the UI but are explicitly outside the required API contract. The homes list returns { homes: [{ id, name }] }, home detail returns { id, name, members: [{ id, homeId, name }] }, and bill listings include each bill’s shares.

I split every bill across all members of its home: each receives the floor of the total divided by the member count, and leftover paise go one at a time to members in the order I added them. This keeps shares equal to the bill total; for example, 1000 paise across three members becomes 334, 333, 333. Bill amounts must be positive whole paise and are rejected before database access if zero, negative, or fractional.

Payment requests require an Idempotency-Key. Repeating the same key for the same share returns 200 with the original paidAt and does not apply payment twice; a different key for an already-paid share returns 409. If two requests try to pay the same share concurrently, one returns 200 and the other 409. A missing key returns 400, and an unknown bill or share returns 404. If payment fails, the share stays unpaid, the error appears under the bill, and balances remain correct.

I store each payment’s idempotency key on its share and claim payment with a conditional update guarded by paid_at IS NULL. If the update changes no rows, I read the share: the same key means a replay and returns 200 with the stored timestamp; a different key returns 409. The conditional update lets the database decide which concurrent request wins, avoiding a separate check-then-write flow that would need a transaction or lock. The key is scoped to one share and cannot be replayed against another share; the contract does not require cross-share replay.

I store member order in an explicit position column because bill splits must follow the order I added members, not an order guessed from IDs. created_at timestamps can be identical for members added in the same millisecond. I assign each member MAX(position) + 1 for their home inside the same INSERT ... SELECT that inserts the member, and a UNIQUE (home_id, position) constraint backs up the ordering guarantee. This adds a column and makes the insert less obvious, but keeps ordering from being accidental.

I write a bill and all its shares together in one D1 db.batch(), which runs as a single transaction, so an error cannot leave a bill without shares or with only part of its shares. I also repeat important API validation rules as named schema constraints: positive whole paise, one share per member per bill, and a complete payment state. That duplication protects the database if a future code path forgets API validation.

I keep the selected home in the URL as /?homeId=… through TanStack Router search params, so the page survives a refresh and a link can be shared. On each Pay click, the web client generates a fresh Idempotency-Key and disables the button while the request is in flight, preventing a double click from sending a second request.

The data model has homes owning members and bills, and each bill has one share per member, with shares joining a bill to a member. The constraints in api/migrations/0001_init.sql enforce that members belong to homes (members_home_exists), member split positions are unique within a home (members_position_unique_per_home), bill totals are positive whole cents (bills_total_is_positive_whole_cents), and a member has at most one share per bill (shares_one_per_member_per_bill). They also require complete payment state—a payment date and key must be present together (shares_payment_state_is_complete)—and prevent shares from surviving deletion of a bill (shares_bill_exists).

When the API returns 500 or is slow, I keep the page layout, show an error and Retry option, and time out every request after 10s.

• The web page shows the current home and its members, bills and shares, an Outstanding section per member, and a Pay button for each unpaid share.
• Loading, empty, and error states are explicit. Every request has a timeout; if a payment fails, the share remains unpaid and the error is shown.
• Names and members are entered through the UI and loaded from the API rather than hardcoded.