🐾 MeowPay — Banking, for Cats

A fintech prototype built from a written specification: persistent balances, atomic transfers, a transaction feed, a leaderboard, and a nap-based credit score — for cats. Built end-to-end (backend, frontend, and an automated test suite) using an AI agent workflow via Claude Code, from spec.md to a green test suite.

25/25 automated checks pass — API correctness, atomicity, persistence across restart, and UI screenshot assertions, all enforced by a black-box checker the implementation never gets to see or edit.

What it does

• Accounts — every cat gets a treat balance and a credit score, seeded with a 100-treat signup bonus.
• Transfers — cats send treats to each other with an optional memo. Rejected for insufficient funds, non-positive amounts, self-transfers, or unknown cats — atomically, so a failed transfer never leaves a half-applied balance change.
• Transaction feed — chronological, per-cat, shows both sides of every transfer plus the signup bonus.
• Leaderboard — ranked by balance, ties broken alphabetically.
• Overdraft hiss — dipping below 20 treats returns a randomly chosen hiss-themed warning (multiple distinct variants, not a single hardcoded string).
• Credit score — derived from the trailing 7 days of logged nap hours, mapped to cat-themed tiers (Feral → Nine Lives Platinum).

Stack

Layer	Tech
Backend	Python, FastAPI, SQLite (file-based, persists across restarts)
Frontend	Plain HTML/CSS/JS — no build step, no framework
Testing	pytest (API contract, business rules, atomicity) + Playwright (screenshot/UI assertions)

Running it

Backend (from backend/):

pip install -r requirements.txt
uvicorn app.main:app --port 8000

Frontend (from frontend/):

python3 -m http.server 8080

Then open http://localhost:8080. No login — pick a cat from the dropdown to "log in" as them.

Full automated check (from the project root):

chmod +x checker/run_checker.sh
./checker/run_checker.sh

Boots the backend, runs the full pytest suite, kills and restarts the backend to prove data survives, boots the frontend, captures screenshots, and prints RESULT: PASS / RESULT: FAIL.

How this was built

The full spec lives in spec.md; the acceptance contract the checker enforces lives in checker/API_CONTRACT.md. Those two files (plus the tests in checker/) were fixed inputs — a human-authored spec and test suite that the AI-driven implementation had to satisfy without being able to see or edit the tests themselves, closer to a real fixed-contract engineering task than a freeform build. CLAUDE.md documents the constraints the agent worked under, and .claude/agents / .claude/skills show the subagent breakdown (backend, frontend, checker runner, judge) used to get there.

Project structure

meowpay/
  spec.md              product spec (source of truth)
  checker/             black-box test suite — API contract, business rules, screenshots
  backend/             FastAPI + SQLite
  frontend/            plain HTML/CSS/JS

Out of scope

Real payment rails, multi-currency, user auth, a mobile app, email notifications — see spec.md Section 8.