Inspiration
Payment scams hit older adults hard: a caller says a grandchild is in trouble, a pop-up claims a refund is owed, or a fake official demands gift cards and tells the victim to keep it secret. The money is usually gone before any family member hears about it.
Most payment apps treat the person at the keyboard as the only decision-maker, even when that person is being pressured in real time. We wanted a system where a trusted family member gets a chance to step in before the money moves, and where AI helps by explaining the risk in plain language instead of just blocking things.
What it does
Family Guardian sits between a senior's payment request and the money actually leaving:
- The senior submits a payment (payee, amount, reason). Nothing is sent yet.
- A hybrid risk engine scores it using fast rules plus Google Gemini.
- Low-risk payments are approved automatically and captured through the PayPal Sandbox.
- High-risk payments are held. The guardian gets an email with a plain-language warning and one-tap Approve / Block links.
- Only approved payments ever reach PayPal. A blocked payment never touches it.
Seniors get a large, simple portal. Guardians get a console with payment history and an audit trail of every decision.
How we built it
- Frontend: React 19 and Vite, with two role-based portals (senior and guardian).
- Backend: Node.js and Express 5 with MongoDB Atlas (Mongoose) and JWT authentication with role checks.
- Risk engine: deterministic rules for known red flags (gift cards, crypto, urgency, secrecy, remote-access tools, unusual amounts), combined with Google Gemini returning structured JSON:
risk,scam_typeand a plain-languageexplanation. A 5-second timeout falls back to the rules if the AI is slow or unavailable. - Payments: PayPal Sandbox Orders v2 with OAuth token caching and a unique
PayPal-Request-Idon every payment as an idempotency key. - State machine:
PENDING → AUTO_APPROVED / HELD → APPROVED / BLOCKED → COMPLETED / FAILED, with invalid transitions rejected. - Guardian actions: signed, 24-hour JWT links in the alert email (via Nodemailer and Mailtrap) so a guardian can act in one tap.
- Quality: 53 Jest unit tests, plus an evaluation script that runs 20 scenarios (10 scams, 10 legitimate payments).
- Hosting: Vercel for the frontend and the serverless backend.
Challenges we ran into
- Never letting a payment hang or double-charge. LLM calls can be slow or fail, so we added a timeout with a rules-only fallback. For retries and double clicks, every PayPal call carries an idempotency key.
- Keeping the flow correct. It's easy to accidentally pay a held or blocked request, so we modeled the lifecycle as a strict state machine and wrote tests for the allowed and rejected transitions.
- Making the AI useful, not just a gate. We wanted guardians to understand why something was flagged, so the model returns a structured explanation instead of a bare score.
- Deploying to serverless. An Express server written for a long-running process needed changes to work on Vercel: on-demand database connections, a function entry point, and correct public URLs. Email action links initially pointed to
localhostuntil the public API URL was configured. - Testing without real fraud data. We wrote 20 scenarios by hand. They show the engine behaves as designed on known cases, but they are not a measure of real-world accuracy.
What we learned
- How payment flows work in practice: OAuth, create vs. capture, and why idempotency matters.
- That the best use of an LLM here isn't replacing judgment but supporting a human decision with a clear explanation.
- Combining deterministic rules with an LLM gives something more predictable, cheaper and easier to explain than either alone.
- How to adapt a normal Express app for serverless hosting, and how to test the safety-critical parts first.
What's next
- PayPal webhooks with signature verification for payment status updates
- A confirmation step for email actions, so email scanners can't trigger them by accident
- SMS or push alerts for guardians
- Warnings in the senior's own language
- Trusted-payee lists and per-senior spending limits
Note: Family Guardian is a hackathon prototype. It runs entirely in the PayPal Sandbox and Mailtrap, so no real money moves and no real emails are sent.
