FortunaCast

Inspiration

We've all been there — staring at a bank account wondering "am I going to be okay?" Budgeting apps tell you what you spent, but they can't tell you what might happen. What if you lose your job for three months? What if your car breaks down next week? What if you just cut back on dining — how much would that actually matter over the next year?

These aren't hypothetical questions. They're the questions that keep people up at night, and no existing consumer tool answers them with real math. Professional risk analysts at banks and hedge funds use Monte Carlo simulation to model thousands of possible futures — but that power has never been accessible to everyday people.

We wanted to change that. Take the same quantitative techniques used on Wall Street, connect them to real banking data through banking API's, and wrap it in an AI advisor that explains everything in plain English. The result is a financial planning tool that feels less like a spreadsheet and more like a conversation with a knowledgeable advisor — one who's already run 5,000 simulations of your future before giving you a single piece of advice.

What it does

FortunaCast connects to your bank account to pull real banking data — accounts, transactions, deposits, merchant categories — and builds a complete financial profile. From that data, it runs 5,000 Monte Carlo simulations to model your possible financial futures over the next 12 months.

Dashboard — A single-screen overview of your financial health. Income, spending by category, net cash flow, emergency fund coverage, savings rate, and a fan chart showing the full range of possible outcomes. Every card is flippable — click it and get a plain-English explanation of what the data means. Hover over any metric for a tooltip explaining it in everyday language.

Simulation Lab — Build your own what-if scenarios from scratch. Adjust your income, add one-time emergency expenses, modify spending per category, simulate months of zero income. Watch the fan chart shift in real time as 5,000 simulations re-run instantly. A ghost overlay shows your baseline so you can visually compare before and after, with a delta summary quantifying exactly how much your outlook changed.

AI Financial Advisor — A conversational AI powered by Claude with full context of your financial profile and simulation results. Ask it anything in natural language — "How healthy are my finances?", "What if I lose my job?", "Can I afford a vacation in August?" — and get personalized, data-grounded responses. Every recommendation references your actual numbers. It maintains conversation history so follow-up questions work naturally.

Goal Planner — Set a savings target and timeframe, and FortunaCast calculates whether you're on track. If not, it tells you exactly which spending categories to cut and by how much, proportionally distributed based on your actual spending patterns. One click applies those cuts to the simulation.

Detailed Analytics — Month-by-month projection tables, outcome distribution histograms, risk contribution charts showing which spending categories drive the most uncertainty, and spending breakdowns with percentage donut charts.

Profile — A complete view of your financial data pulled from Nessie: accounts, balances, spending categories with variance metrics, income analysis, and recurring bills. Refresh anytime to pull the latest from the API.

How we built it

Monte Carlo Engine (Python, NumPy) — The simulation engine is fully vectorized. Balances are computed as $\text{starting_balance} + \text{cumsum}(\text{income} - \text{spending})$ across all simulations using array shapes $(S, M)$ where $S = 5{,}000$ simulations and $M = 12$ months. Variable spending uses correlated standard normals — we build a positive semi-definite correlation matrix $R$ between categories (e.g., dining and entertainment at $\rho = 0.52$), compute the matrix square root $W = V\sqrt{\Lambda}V^T$, and transform independent normals via einsum: $X_{s,m,:} = G_{s,m,:} \cdot W$. This gives each simulated month a spending vector with realistic covariance structure. We model seasonal effects (December 1.18×, summer 1.08× on variable spending), income loss periods, one-time shock expenses, and use sensitivity analysis to identify the biggest risk factor by re-running with each category's variance zeroed out. The full batch completes in ~30-40ms.

Nessie Integration — We built a complete integration with Capital One's Nessie API: a client wrapper for all endpoints, a profile builder that categorizes transactions by merchant type, groups purchases by calendar month, computes per-category statistics, and estimates income from deposit patterns. We also built a seeding system that creates 6 months of realistic transaction history across 8 merchant categories with month-to-month variance.

AI Layer (Claude API) — Three modes of AI interaction: baseline financial reports (3-paragraph advisor-quality analysis with quantified recommendations), comparison reports contrasting baseline vs. stress scenarios, and free-form conversational chat with the last 10 messages as context. Every request injects the full financial profile and simulation metrics so responses are always grounded in real data.

Frontend (Next.js, TypeScript, Tailwind, Recharts) — A multi-page dashboard with Capital One branding. Six pages connected through a sidebar navigation, all sharing state via a React context provider. The fan chart uses stacked Recharts area layers for percentile bands with ghost baseline overlays. We built custom components: flippable explanation cards with 3D CSS transforms, a portal-based tooltip system, a ChatGPT-style chat interface with typing indicators, and a custom stress test builder with income, expense, and per-category spending controls.

Architecture — FastAPI backend serving the simulation engine, Nessie integration, and AI layer. Next.js frontend with API proxy rewrites to avoid CORS. Pydantic data models serve as the contract between all backend modules. The codebase was structured for three-person parallel development with separate folders and shared interfaces.

Challenges we ran into

Nessie API documentation gaps — The API docs were minimal. We discovered through trial and error that create endpoints return data nested inside objectCreated, that purchases require undocumented fields like medium and description, and that merchant categories don't always match expected values. We built a keyword-based categorization system with name hints (e.g., "Bistro" → dining, "CVS" → healthcare) to handle edge cases.

Making the fan chart visually meaningful — Our first several iterations produced flat, boring charts because the demo profile was too financially comfortable. A $33,000 checking balance with $400/month net cashflow shows almost zero risk. We iterated on seed data, tuned starting balances, and added a starting_balance_override parameter to control the simulation independently from accumulated Nessie deposits.

Correlated spending modeling — Real spending categories aren't independent. Implementing the correlation matrix with proper PSD enforcement (eigenvalue clipping and rescaling) and the einsum-based transform — avoiding matmul which produced divide-by-zero warnings on macOS Accelerate — required significant debugging to get mathematically correct and numerically stable.

Next.js caching — At one point, our frontend was serving JavaScript bundles from a deleted copy of the project sitting in the macOS Trash. Changes to source files weren't appearing no matter how many times we cleared the cache. We had to trace the Node process's working directory to discover the issue.

Three-person parallel development — Coordinating three developers at a hackathon without constant merge conflicts required upfront architecture decisions. Shared Pydantic models as the data contract, separate folders per person, mock data for independent development, and a clear push order for files that multiple people touched.

Accomplishments that we're proud of

The Monte Carlo engine is genuinely sophisticated. This isn't a toy simulation — it models correlated spending, seasonal effects, income volatility, shock events, and uses sensitivity analysis for risk attribution. The same techniques are used by quantitative finance teams at real banks. And it runs 5,000 simulations in under 40 milliseconds.

The AI advisor actually knows who you are. Every response from Claude references the user's real spending numbers, real probabilities, and real risk factors. Ask "What if I lose my job?" and it tells you your 12-month solvency drops from 100% to 34% and recommends cutting dining by $200/month to mitigate. This isn't generic advice — it's advice grounded in 5,000 simulated futures.

The custom stress test builder. Users can construct any scenario — partial income loss, emergency expenses, spending increases across specific categories — and see the probabilistic impact in real time. The ghost baseline overlay makes before-and-after comparison intuitive and immediate.

The full Nessie pipeline. Real banking data flows from the API through categorization, statistical analysis, Monte Carlo simulation, and AI interpretation — end to end. The profile builder handles merchant categorization, monthly grouping, income estimation, and variance computation automatically.

Flippable explanation cards and tooltips. We made quantitative finance accessible. Every metric has a plain-English tooltip. Every major visualization can be flipped to reveal an explanation of what it means and why it matters. You don't need a finance degree to use FortunaCast.

What we learned

• Monte Carlo simulation is surprisingly accessible to implement — the core engine is ~100 lines of NumPy — but making it realistic with correlations, seasonality, and sensitivity analysis is where the real engineering challenge lives
• Prompt engineering for financial advice requires extreme specificity. Generic prompts produce generic advice. Injecting the full numerical context and requiring dollar amounts in every sentence made the difference between "consider reducing spending" and "reducing dining by $200/month raises your 6-month solvency from 78% to 94%"
• The gap between "it works" and "it demos well" is enormous. Seed data quality, starting balance tuning, chart color choices, tooltip positioning, and fan chart spread all matter as much as the core algorithm
• Structuring a hackathon codebase for three-person parallel development from hour zero — with shared data contracts, mock data, and separate ownership folders — saved us countless merge conflicts and dramatically increased our velocity
• Real banking APIs are messy. Transaction categorization, income pattern detection, and building meaningful statistical profiles from raw purchase data requires thoughtful heuristics, not just API calls

What's next for FortunaCast

• Real bank integrations — Replace Nessie with Plaid to connect to actual bank accounts, enabling anyone to simulate their real financial future
• Historical backtesting — Run the simulation against past data to validate accuracy: "If you had used FortunaCast 12 months ago, here's how accurate our predictions would have been"
• Collaborative finance — Shared households, roommates, or couples could merge profiles and simulate joint financial futures, stress-testing scenarios like "What if one of us loses our job?"
• Mobile app — A React Native version with push notifications: "Your spending this week puts you in the 30th percentile of simulated outcomes — consider cutting back to stay on track"
• Advanced debt modeling — Credit card interest accumulation, minimum payment strategies, and debt payoff optimization integrated into the simulation engine
• Community benchmarking — Anonymous peer comparisons: "Compared to others with similar income, your savings rate is in the bottom 25%" to contextualize individual results

Built With

• capital-one-nessie-api
• claude-api-(anthropic)
• fastapi
• framer-motion
• httpx
• next.js
• numpy
• pydantic
• python
• react
• recharts
• reportlab
• tailwind-css
• typescript