[PROJECT NAME] — the bill splitter that actually knows what things cost

One-liner: Snap any messy real-world receipt, split it in a few taps, settle in one scan. Most apps make you type every line; this one reads the receipt for you.

The problem

Splitting a group bill is tedious. The real friction is data entry: someone squints at a crumpled receipt and types every line item by hand, gets abbreviations and quantities wrong, and the splitting only starts after that chore. Existing apps assume the items are already clean. Real receipts are not.

What it does

1. Snap the receipt. The hard part, and the core of the product: a vision model reads messy, real-world receipts, crumpled, low-light, abbreviated, ambiguous quantities, and turns them into clean structured line items with prices, tax, and tip.
2. Assign with a tap. A simple UI lets the group mark who had what and flag shared items.
3. Split. Shared items divide among the people who shared them; tax and tip distribute proportionally. Per-person totals, instantly.
4. Settle up. Generates a PayNow QR so everyone pays in one scan.

The intelligence is in the reading, not the arithmetic. Getting from a photo of a real receipt to correct structured items is the part everyone else skips.

How we use the sponsor tech

A vision-capable model is the engine of the product, not a feature on the side: the entire intake depends on it. [TODO: name the sponsor model you used] reads the raw receipt photo and outputs structured line items, handling the cases that break naive OCR, faded thermal paper, abbreviations like "MKT PRICE", multi-quantity lines, items wrapping across rows, and inferred tax/tip. Without it there is no app; everything downstream runs on what it extracts. [TODO: add the one clever extraction behavior you're proudest of, e.g. "splits a single '2x LATTE 9.00' line into two assignable units automatically".]

Demo

[DEMO LINK]

Scripted demo flow: [TODO: name the example receipts you rehearsed. Include one clean receipt AND one deliberately messy/crumpled one, the messy one is where the vision model visibly earns its 30%.]

Tech stack

• Frontend: Vite + React + TypeScript (frontend/)
• Backend / orchestration: Express + TypeScript (backend/)
• Receipt understanding (vision): [TODO: sponsor model]
• Splitting logic: [TODO] (rules in CONTRACT.md: integer cents, GST on subtotal+service, proportional charge distribution)
• Payments: PayNow QR generation via [TODO: library]

Architecture

Receipt image → vision model (structured line items, see CONTRACT.md) → assignment UI → split logic (shared items + 10% service + 9% GST) → per-person amounts → PayNow QR.

Known limitations

• Receipt reading can still miss on extreme cases (heavy damage, handwriting, non-Latin scripts). [TODO: state what you actually handle and what you don't; an editable line-item view as a fallback is worth a sentence here.]
• PayNow QR: [TODO: state whether amount is encoded (dynamic) or payer enters it (static), based on what actually parses in a real banking app]

Team

• Ron — deployment + receipt OCR (vision model)
• Ray — frontend
• Zavier — split logic + PayNow QR [TODO: add demo ownership; with no 4th person, assign who owns the demo script + curated receipts.]

Setup

The repo is split in two:

frontend/   Vite + React + TS app (the step flow, split logic, PayNow QR)
backend/    Express + TS API (the server-side vision scan endpoint)

Run both in separate terminals:

# Terminal 1 — backend (http://localhost:3001)
cd backend
npm install
cp .env.example .env      # add ANTHROPIC_API_KEY when wiring the real vision call
npm run dev

# Terminal 2 — frontend (http://localhost:5173)
cd frontend
npm install
npm run dev               # VITE_API_URL defaults to http://localhost:3001

The frontend talks to the LAN (host: true in vite.config.ts), so you can open it on a phone on the same wifi for demos. The "Skip — use sample receipt" button runs the whole flow without the backend.

Where each person's work plugs in:

• Receipt vision (Ron): backend/src/lib/vision.ts — replace the mock in readReceipt() with a real model call. Return type stays ScanResult.
• Split logic (Zavier): frontend/src/lib/split.ts — implements CONTRACT.md; pinned by frontend/src/lib/split.test.ts (npm test).
• PayNow QR (Zavier): frontend/src/lib/paynow.ts — EMVCo payload generator. ⚠️ Scan-test the output with a real banking app before the demo.
• Frontend (Ray): frontend/src/components/ — one file per step.