Income Firewall

Income Firewall

Inspiration

I used to do freelance gigs before, and my income was all over the place. Some months I'd make bank, other months I'd be broke; and I kept thinking it was a budgeting problem. That I was just bad with money or spending too much. Turns out, it wasn't overspending. It was poor allocation. I'd have a 6,000 month and live like it, then a 1,200 month would hit and I'd panic. No app was telling me: 'Hey, you need to park 30% of this big check because your income bounces this much.' So I built the thing I wish I had back then.

What it does

Statistical modeling isn't just math - it's product design. I learned that choosing bootstrap sampling over a normal distribution wasn't just a technical decision; it was a product decision. Creators have "viral months" and gig workers have "injury months." If I'd assumed a neat bell curve, the model would have given dangerously optimistic advice.
Stability matters more than features. Midway through, I realized a pretty UI with unstable numbers would lose all credibility. That's why I stopped adding features and invested time in Common Random Numbers (CRN) and seasonal bucketing. The goal became: "When I toggle smoothing on and off, the difference should reflect the policy, not randomness."
The adapter pattern is magic. Building the engine to accept IncomePoint[] regardless of source meant I could add CSV uploads, Nessie API, and sample profiles without touching the core logic. That one architectural decision saved hours of refactoring.

How we built it

Tech Stack: Framework: Next.js 16.1.6 with App Router (TypeScript) Styling: Tailwind CSS (dark theme) Charts: Recharts for trajectory visualization APIs: Capital One Nessie (banking sandbox) Validation: Zod + react-hook-form Deployment: Vercel-ready (API routes + frontend together)

Architecture: Frontend (React) → API Routes (/api/analyze, /api/nessie) → Engine (lib/engine/) ↓ CSV Adapter, Nessie Adapter ↓ Synthetic 60-month datasets

Key Implementation Phases: Hour 1-4: Core engine with bootstrap Monte Carlo, feature computation, recommendation logic Hour 5-8: Frontend dashboard with KPI cards, chart, basic input forms Hour 9-12: CSV synthetic datasets (60 months, 3 profiles with realistic seasonality) Hour 13-16: Stability upgrades (CRN, seasonal bucketing) + backtest engine Hour 17-20: Nessie API integration with caching and graceful fallbacks Hour 21-24: Polish demo flow, allocation replay table, backtest summary

Challenges we ran into

Avoiding “Just Another Budget App” One of the earliest challenges was conceptual. It was very easy to drift into building a traditional expense tracker or budgeting dashboard. Those are common and visually impressive, but they don’t solve the volatility problem I cared about. The challenge was forcing the product to stay centered on risk modeling, not expense categorization. That meant resisting feature creep (sliders, visual gimmicks, extra charts) and instead focusing on probability, simulation, and policy evaluation.
Making Monte Carlo Results Stable Monte Carlo simulations introduce randomness by nature. Early versions of the model would sometimes show that the smoothing plan helped… and other times it didn’t — purely due to different random draws. That was a serious credibility issue. The solution was implementing Common Random Numbers (CRN) so that baseline and smoothing simulations use the same pre-generated random seeds. This made comparisons apples-to-apples and ensured that any improvement was due to the policy — not randomness. This was one of the most important technical turning points in the project.
Modeling Seasonality Without Overcomplicating the Engine Plain bootstrap sampling ignores seasonal patterns. For creators and gig workers, this would distort reality (e.g., Q4 brand spikes or summer demand). The challenge was: Incorporating seasonality Without turning the project into a full forecasting system The compromise was implementing seasonal buckets by month-of-year, with fallback logic when data was sparse. This preserved patterns while keeping the model lightweight enough for a hackathon.