A fifteen-dollar refund looks small until you see what the order actually earned.
The sale has already paid for processing, goods and shipping. A merchant needs to understand the trade-off without turning a customer request into a spreadsheet exercise. Just as importantly, a convincing explanation is not payment evidence, and a model suggestion is not permission to move money.
I built MarginGuard around that separation: evidence first, deterministic money second, human decision always.
What it does
MarginGuard is a refund decision workspace for the fictional merchant Kiln & Field. It brings the request, capture evidence, processing fee, goods cost and shipping into one packet. Changing a proposed refund shows what contribution remains. Missing fees, mismatched capture evidence and pending captures block approval instead of producing reassuring guesses.
The local build connects a genuine PayPal Sandbox capture to MG-1001, a studio mug order. The $80 sale reported a $2.56 fee and $77.44 net. After an explicitly human-approved $15 sandbox refund, contribution is $28.44 using fictional goods cost of $28 and shipping of $6. The remaining refundable amount is $65. No live money moved.
The AI supplies a second read, not a decision. Cloudflare Workers AI interprets the fictional request, explains allowlisted facts, identifies caveats and questions, and prepares an unsent reply for review. Financial numbers are calculated by code. The AI cannot approve a refund or call PayPal.
Eleven other orders remain visibly fictional. Their approvals create local simulations, not sandbox transactions. The activity ledger records human approval and completed sandbox refund evidence separately from simulations and imported balance snapshots.
How I built it
The client uses React 19, TypeScript and Vite. A Hono API on the Node server serves the client and API together. Pure domain modules perform safe integer-cent calculations and reconciliation. Zod validates API and model boundaries. SQLite is the local stand-in for a future D1 implementation; D1 is not deployed in this build.
The server-only PayPal adapter uses Orders v2 for sale setup and Payments v2 for capture/refund evidence and refunds. It accepts only the official Sandbox API origin and refuses fictional fixture capture IDs before network access. Exact approvals bind the order, amount, currency and evidence. The approval ID becomes the PayPal idempotency request ID. Non-completed outcomes do not become successful local receipts.
Cloudflare Workers AI runs IBM Granite 4.0 H Micro with prompt version advisory-v4. Model responses must pass strict schemas. Numeric and completed-action claims in model prose are filtered, while displayed amounts remain server facts. Invalid output is withheld for human review. Inference begins only on an explicit advisory request and has bounded timeouts, a shared repair limit, session-scoped caching and process-local request caps.
Challenges I ran into
The hardest boundary was not drawing a before-and-after figure. It was keeping that figure honest when evidence is missing, a proposal changes, or an external request has an uncertain outcome.
I separated the deterministic Decision brief from generated advice, and bound approvals to complete evidence snapshots. I also separated fictional fixtures from attached sandbox captures at the UI, adapter and execution boundaries.
A new local session is not a new PayPal balance. The app now accepts an optional, manually verified prior-refund snapshot so a new session can display a completed refund without executing it again. That import is labeled as a snapshot and does not manufacture a PayPal receipt. Automatic reconciliation and durable cross-session external refund recovery remain future work.
Accomplishments that I'm proud of
The meaningful loop worked locally: a genuine sandbox sale, observed fee evidence, a human-approved sandbox refund and the resulting contribution displayed in the running app. The AI integration also ran locally, while retaining no payment authority.
The same interface shows why a missing fee must stop a decision. That contrast matters: a useful financial assistant needs a credible refusal path as much as a success path.
What I learned
A financial interface should distinguish four things clearly: evidence, assumptions, advice and authorization. Putting all four in one fluent paragraph would make the app feel simpler while making the decision less trustworthy.
I also learned that local idempotency and external payment correctness are different problems. A sandbox demonstration is not a production recovery system. The build documents those limits rather than hiding them behind the word safe.
What's next
Durable capture-wide reservations, authoritative reconciliation, crash recovery, authenticated merchant isolation and broader adversarial AI evaluations come before real financial use. An asynchronous D1-backed store would require redesigned transaction semantics, not a database-name swap. Accessibility and clean judge-install rehearsals are further release checks.
Built With
- 4.0
- ai
- cloudflare
- granite
- h
- hono
- ibm
- micro
- node.js
- orders
- payments
- paypal
- react
- sqlite
- typescript
- v2
- vite
- vitest
- workers
- zod