Inspiration
For as long as I have managed my own finances, I have been trapped in the same frustrating predicament: every budgeting app I ever used would only inform me after I had already spent the money.
All the charts, notifications, and financial lectures would arrive long after the damage was done. While those insights were informative as I sat there regretting an impulsive purchase, they always arrived when I was in a significantly worse position. Traditional personal finance tools essentially perform financial autopsies—they tell you how you died financially, rather than preventing the fatal blow in the first place.
I always wished that the guidance, friction, and teachings had come before I had already tapped checkout and drained a substantial part of my rent money. Too many times, I found myself facing the grim reality of living off instant ramen and water for a week just to make ends meet until the next time my allowance came. Under one-tap checkout culture and blended account balances, nothing stopped my impulsive 1:00 AM food delivery order from eating into money that had been mentally earmarked for electricity or rent.
That lived frustration inspired FireWallet: The Trinity System. I wanted to build a proactive financial firewall—an intelligent gatekeeper that intercepts the transaction before money leaves your wallet, protects your foundation, and forces you to confront the real impact of your choices before the damage is done. Though I had made the system named "Trinity System", which set me on a daily budget rather than monthly so that I don't overspend on any given day, and if I could stay in budget during the day, the monthly budget would take care of itself. But it was never actually enforced through any app or guardrail and was only something I would do by having 3 accounts and transferring money every morning. Which I must tell you, never worked; nothing stopped me from using the bank account directly to pay for stuff often exceeding my budget, and what if something urgent came up where the daily budget had to be breached? Hence, This App is my answer to my and every student's frustration. This could also arguably help a lot of people besides students as well.
What it does
FireWallet is an intent-first financial firewall and proactive AI coach engineered around the Trinity Bucket Architecture:
The Trinity Bucket Engine: Rather than keeping funds in a single, easily depleted pool, FireWallet partitions capital into four mathematically strict buckets:
- Bank (Foundation): The bedrock cash-flow engine where income lands and bills/rent are strictly earmarked. Direct merchant spending is hard-locked.
- Daily Allowance (Living Engine): Fluid daily spending money for essentials. It features the Rollover Rule: unspent daily cash rolls forward into the next day, actively compounding and rewarding restraint.
- Freedom Bucket: A pre-allocated, guilt-free monthly hedonism fund for entertainment and impulse spending. Once it is empty, spending hard-stops.
- Vault (Locked Reserve): An emergency reserve and goal fund funded by an automated 20% skim on payday via PayPal Payouts, locked by default.
Intent-First Gateway: Before any PayPal transaction can be authorized, the user must state why they are spending (e.g., "$24.00 for groceries at Safeway" or "Late-night sneakers purchase"). An AI Intent Parser analyzes the purchase's necessity, while our deterministic ledger engine checks liquidity against bucket policies.
The Escape Window: If an impulsive user attempts to raid their protected Bank foundation to fund non-essential lifestyle creep, there is no one-tap bypass. The system activates the Escape Window: a mandatory 200-character written reflection and a server-enforced 3-minute psychological cooldown timer. It gives human self-control a second chance to prevail.
Dual-Surface Interface:
- Mobile HUD (
/): A thumb-friendly, minimalist Heads-Up Display showing live rollover balances, category health, and a Quick Intent floating action button. - Desktop Deep Ledger (
/analytics/deep-ledger): An enterprise-grade workbench powered by AG Grid, allowing deep ledger audits, multi-column sorting, transaction state grouping (hold,posted,released), and direct interrogation by our AI Coach.
- Mobile HUD (
Advanced Reasoning Coach: A conversational financial mentor that evaluates plain-English affordability queries ("Can I afford dinner out tonight?"), explains visual financial charts (
chart_id), and diagnoses spending velocity directly from active AG Grid filter states.
How we built it
We built FireWallet as a modern, split full-stack monorepo with financial-grade invariants and sponsor tooling:
- Backend & Ledger Engine: Built with FastAPI in Python 3.12, managed with
uv. The database layer uses SQLModel (supporting asynchronous SQLite and PostgreSQL). To eliminate rounding errors and floating-point exploits, the entire ledger enforces zero-float accounting—all monetary balances are tracked in 64-bit integer cents. - PayPal Sandbox Integration: FireWallet connects directly to PayPal's REST APIs:
- Orders v2 API: Implements a strict Hold-Then-Execute pattern. An atomic row lock (
SELECT FOR UPDATE) places a ledgerHOLDon the bucket before calling PayPal's Orders API. Only after the user approves the payment and PayPal settles the transaction is the hold released and debit posted. - Payouts API: Dispatches automated Vault skims and bill payouts exclusively to verified destination accounts.
- Cryptographic Webhook Verification: The
/api/v1/webhooks/paypalendpoint cryptographically verifies PayPal webhook signatures and enforces event idempotency to prevent duplicate debits.
- Orders v2 API: Implements a strict Hold-Then-Execute pattern. An atomic row lock (
- AI Proposal & Deterministic Policy Layer: Powered by Groq's low-latency inference (
openai/gpt-oss-120bwith OpenAI fallback). We separated responsibilities rigorously: the AI parses intent, summarizes context, and proposes actions, but deterministic Python policy rules gate money movement. The LLM never touches the ledger directly. - Frontend & Data Grid: Built with React 18 and Tailwind CSS. For high-density analytics, we integrated AG Grid Enterprise on the Desktop Deep Ledger, providing users with instant multi-column filtering, state grouping, and audit exports.
- API Consistency & Tooling: We utilized APIMatic to generate typed OpenAPI contracts from our FastAPI schema to eliminate AI hallucination during development. We automated endpoint smoke tests using a pre-configured Postman Collection, and authored deployment blueprints for Render (
render.yaml).
Challenges we ran into
- The Late Discovery Crunch: I only discovered the PayPal AI Hackathon on October 26th. Having harbored this concept for so long, I decided to jump in headfirst despite having just over two weeks to deliver a production-grade full-stack financial system.
- The Double-Edged Sword of AI Code Acceleration: I had always strictly bound myself to the rule of never using AI to write code until I thoroughly understood the underlying concepts myself. Under the immense pressure of the timeline, however, I couldn't afford to be picky with my tools. I leaned heavily into modern AI assistants to accelerate development.
What I discovered was eye-opening: debugging AI-generated code was an absolute pain. While writing code manually is slower upfront, you catch architectural assumptions and edge-case errors early. Reviewing and untangling code produced by an AI was a completely different learning curve. It required meticulous auditing, writing defensive unit tests, and hunting down subtle logic mismatches. While edge-case bugs inevitably still exist in a project of this architectural scope, rigorous manual review ensured that the core MVP works reliably for the demo.
- Concurrency & Ledger Invariants: Building a real payment gateway means race conditions can cause double-spending. Engineering the Hold-Then-Execute flow with row-level locks and ensuring that asynchronous PayPal webhooks settled idempotently without ledger drift required several rewrites and intense testing.
- Balancing Friction with Usability: Designing the Escape Window required careful calibration. If friction is too light, users bypass it; if it is too frustrating, they abandon the app. Balancing a mandatory 200-character reflection with an un-gameable 3-minute server cooldown was one of the trickiest behavioral challenges of the project.
Accomplishments that we're proud of
- A Real, Working Financial Core: FireWallet does not use mock balances or cosmetic checkouts. Every balance change reflects actual money movement through the PayPal Sandbox API.
- The Rollover & Escape Window Mechanisms: Bringing the mathematical rollover rule and the psychological Escape Window to life. Watching an impulsive spend get halted by a 3-minute cooldown with a prompt asking for honest reflection is genuinely satisfying.
- Zero-Float Accounting Integrity: Achieving complete mathematical consistency across double-entry ledger transfers using pure integer cents.
- Enterprise-Grade AG Grid Integration: Crafting the dual-surface experience where users can switch from a streamlined mobile HUD to a rich, high-density AG Grid desktop workbench that directly feeds into the AI Coach.
- Delivering a Working MVP in Two Weeks: Going from an empty repository on October 26th to a fully documented, fully testable, and functional hackathon submission before the deadline.
What we learned
This hackathon fundamentally altered my perspective on software development and tooling:
- The Reality of AI-Assisted Engineering: Breaking my personal rule of "no AI code generation until understood" taught me that AI is an incredible accelerator for boilerplate, schemas, and scaffolding, but it is not a replacement for deep architectural understanding. Reviewing code written by someone (or something) else is a vital skill. You must treat AI output with healthy skepticism, backing every endpoint with automated tests and strict typing.
- Deterministic Guardrails are Mandatory in Fintech: You cannot trust an LLM with account balances or execution permissions. The
Propose → Verify → Confirm → Executepipeline reaffirmed that AI belongs in the proposal and reasoning tier, while deterministic, hard-coded rules and atomic database locks must govern real-world assets. - The Value of Developer Tooling: Embracing tools like
uvfor blazing-fast Python environment management, AG Grid for instant data visualization, APIMatic for schema verification, and Postman for automated API smoke-testing saved countless hours and kept the project organized under extreme time pressure.
What's next for FireWallet: The Trinity System
While the hackathon MVP proves the viability of an intent-first financial firewall, this is only the beginning for FireWallet:
- Ironing Out the Remaining Edge Cases: Continuing to audit and refine the codebase, hunting down the subtle bugs uncovered during rapid prototyping, and optimizing ledger query performance.
- Direct Open Banking & Debit Card Interception: Expanding beyond PayPal sandbox checkout to hook into real-time card and bank rails (via Plaid or Open Banking APIs), bringing intent-first protection to physical Point-of-Sale swipes.
- Automated Long-Term Wealth Sweeps: Integrating recurring PayPal Payouts to automatically sweep matured Vault savings into high-yield accounts, index funds, or external investment portfolios.
- Multi-Currency & Global Rollover: Adding automated currency conversions across international PayPal wallets while preserving localized daily rollover calculations.
- Native Mobile Experience: Packaging the Mobile HUD into native iOS and Android apps with biometric authorization, real-time push notification interventions, and lock-screen intent prompts.