This is a submission for the MLH × DEV Writing Challenge
Your bank balance tells you how much money you have. CashCompass tells you how much you can actually afford to spend.
That single difference inspired us to build CashCompass, an AI-powered personal finance platform at SwampHacks XII 2026.
Over one hackathon weekend, we brought together AI, financial forecasting, banking APIs, real-time collaboration, blockchain payments, and even a Roblox game.
But behind all those technologies was a problem almost everyone has experienced.
You check your bank account. You see $2,250. You want to buy a $1,200 MacBook.
Technically, you have enough money.
But your rent is due before your next paycheck.
Can you really afford it?
That's the question CashCompass was built to answer.
🌐 Live app: cashcompass.club
💻 GitHub: View the CashCompass repository
🎮 MoneyQuest: Play CashCompass MoneyQuest on Roblox
💡 The Problem: Money Isn't Just About How Much You Have
Most personal finance applications focus on historical information.
They tell you where your money went, how much you spent on groceries, whether you exceeded your shopping budget, and how your account balance changed.
That's useful, but it misses something important.
Financial stress often comes from timing, not totals.
A person might have $2,000 available today but owe $1,500 in rent tomorrow.
A friend might promise to repay $300 on Friday, but that money could arrive late.
A purchase might be perfectly reasonable next week but risky today.
Traditional dashboards don't always make these relationships obvious.
We wanted to create a financial companion that understands the entire timeline of your money, including what's already happened, what's expected to happen, and what could happen if you make a different decision.
That's how CashCompass started.
🧭 Introducing CashCompass
CashCompass is an AI-powered personal finance platform designed to help users track, plan, simulate, and make smarter financial decisions.
Rather than building another expense tracker with an AI chatbot attached, we developed a connected financial system.
The application combines a personal finance dashboard, transaction management, credit-card and bill tracking, receipt scanning, shared-expense management, savings goals, a financial simulator, and a Gemini-powered AI copilot.
Every feature connects back to the user's financial timeline.
A new bill changes the forecast.
A savings contribution affects available spending money.
A delayed repayment changes the conservative outlook.
A planned purchase can be simulated before it becomes real.
We wanted CashCompass to help people answer a more useful question:
"What happens to my finances if I make this decision?"
📈 The Feature We're Most Proud Of: The What-If Simulator
The heart of CashCompass is its deterministic cash-flow simulation engine.
Users can explore financial decisions without changing their actual transactions.
Imagine asking:
"What if I buy a $1,200 MacBook today?"
CashCompass simulates the purchase against your financial timeline.
It accounts for recurring income, upcoming bills, everyday spending, expected repayments, planned savings, and your emergency buffer.
It then compares your projected balance against the original forecast.
Users can also simulate buying after payday, delaying a bill, receiving a repayment late, or saving a fixed amount each week.
The interface visualizes both the baseline and the hypothetical scenario on the same chart.
It also reports the minimum projected balance, the number of bills at risk, and the biggest difference caused by the decision.
The most important design choice is that simulations are reversible.
What-if events exist only inside the scenario calculation. They never modify actual financial records.
Safe to Spend: A Better Number Than Your Balance
We also introduced Safe to Spend, a metric that estimates how much money a user can spend without compromising known upcoming obligations.
Instead of displaying the current balance as though it's all disposable income, CashCompass accounts for bills due before the next paycheck, planned savings, outstanding debts, estimated everyday spending, and an emergency buffer.
Our demonstration scenario shows why this matters.
A user can have $2,250 available, while the amount considered safe to spend is only around $92.
It's a small distinction in the interface, but a meaningful distinction in financial decision-making.
We also calculate expected and conservative forecasts.
An uncertain repayment is included in an optimistic outlook, but excluded from the conservative calculation.
That means money someone promises to send isn't automatically treated as money you can safely spend.
CashCompass looks at when money moves, not just how much money exists.
🤖 Gemini: An AI Copilot That Doesn't Invent Financial Numbers
One of our biggest engineering challenges was deciding how AI should interact with financial data.
Large language models are great at understanding natural-language questions.
But asking an LLM to calculate your entire financial future from memory is a bad idea.
Financial answers need consistency, traceability, and predictable mathematics.
So we designed a hybrid architecture.
Architecture: Natural-language question → Gemini → Validated tool arguments → Deterministic financial engine → Verified result → User-friendly explanation
Gemini understands what the user wants.
The financial engine handles the calculations.
Then the system turns those results into a readable explanation.
For example:
"Can I afford a MacBook today?"
The AI identifies the purchase and relevant parameters.
CashCompass evaluates the purchase against the forecast using structured financial events.
The response explains the outcome using the calculated results instead of allowing the model to invent balances or projected dates.
We also implemented validation, structured response handling, model fallbacks, and an offline response path.
This separation became one of our core engineering principles:
Use AI for intelligence and communication. Use deterministic code for financial truth.
The Gemini integration extends beyond the chat interface, too.
📸 AI-Powered Receipt and Bill Scanning
We wanted adding a bill to feel as easy as taking a picture.
CashCompass supports receipt and bill uploads, webcam capture, and a QR-based phone-scanning workflow.
If you're using a laptop and the receipt is in front of you, you can scan a QR code on CashCompass, open the capture page on your phone, and take a picture there.
The image is sent back through a temporary upload session.
Gemini helps extract useful information such as the merchant, amount, date, and category.
The user then reviews the extracted information before saving it.
We intentionally avoided automatically trusting an AI interpretation of a financial document.
For us, AI suggestions and confirmed financial records are two different things.
We also created a dedicated Receipt Log so a restaurant payment that already happened isn't confused with a future bill.
Users can add notes, categorize purchases, review receipt history, and associate receipts with shared expenses.
💸 Settle Up: Shared Expenses Without the Spreadsheet
Splitting expenses is one of those everyday tasks that becomes frustrating surprisingly quickly.
Maybe you paid for groceries.
Maybe your roommate owes half the rent.
Maybe four friends went to dinner, but everyone ordered different things.
CashCompass includes Settle Up, a shared-expense management system inspired by the simplicity of Splitwise.
Users can add friends, track who owes whom, create balances, record partial repayments, send reminders, and associate receipts with shared bills.
For splitting an expense, users can select an existing receipt or create a new bill.
They can divide the expense equally, enter exact amounts, or use our AI-assisted allocation workflow.
Tell Gemini Who Ate What
Consider a restaurant bill shared by three people.
Instead of manually calculating everyone's share, users can describe the situation:
"I had pasta, Alex had pizza, Sam had a burger, and we shared the fries."
Gemini proposes individual allocations from the description.
It can account for shared items and distribute unattributed charges such as tax or tip.
But the AI doesn't get the final say.
We built deterministic reconciliation and validation so the shares add up to the actual bill total.
The calculation uses integer cents to avoid common floating-point rounding errors.
Users can review and edit the suggested amounts before confirming the split.
Once confirmed, the appropriate receivables are created in the financial ledger.
That also means expected repayments can become part of the CashCompass forecasting model.
A shared dinner expense is no longer just an entry in a ledger. It can influence future financial decisions.
🌐 Real-Time Collaboration With DeepSpace
We also extended our shared-expense experience with a DeepSpace Live Split Room.
Instead of treating bill splitting as an entirely individual activity, the Live Split Room provides a collaborative space for working through shared expenses.
The goal is to make splitting a bill feel like something friends do together, rather than something one person calculates and sends to everyone else.
CashCompass provides an entry point to the dedicated DeepSpace companion experience directly from Settle Up.
The separation between the collaborative experience and the main financial application is intentional.
Our financial ledger manages recorded obligations and payments, while the live room focuses on coordinating the shared-expense experience.
This was an important product-design lesson: some financial decisions are individual, but shared expenses are fundamentally social.
🤝 DeepSpace Live Split Room: Open the Live Split Room
🏦 Banking Integration With Capital One Nessie
To connect CashCompass with banking workflows, we integrated the Capital One Nessie API.
Nessie provides a sandbox for simulated banking data and transactions.
Through this integration, CashCompass supports account selection, transaction synchronization, expense categorization, and peer-to-peer transfer workflows.
We also addressed a less visible but important engineering problem: duplicate imports.
When the same account is synchronized multiple times, the application should not create multiple copies of an existing transaction.
Our synchronization logic uses stable source identifiers and reconciliation checks to recognize previously imported activity.
We also distinguish pending purchases from future bills so spending isn't incorrectly counted twice.
Nessie allows us to demonstrate realistic banking behavior while keeping the application a sandbox-based financial prototype rather than a connection to users' actual bank accounts.
🗄️ Tiger Data: Financial Events as Time-Series Data
Money is naturally time-based.
Every transaction, bill, paycheck, savings contribution, and repayment belongs somewhere on a timeline.
That made Tiger Data and TimescaleDB a natural fit for CashCompass.
We structured financial events in PostgreSQL with time-series capabilities, including a hypertable partitioned by event date.
We also implemented a monthly category-spending continuous aggregate and configured compression for older event data.
Our database design separates records by authenticated user, allowing queries and analytics to be scoped to the correct account.
This architecture helps support the relationship between historical spending and forward-looking financial analysis.
For example, historical transaction activity informs the everyday spending estimate, which then affects future cash-flow projections.
We also learned an important infrastructure lesson: a schema can support powerful analytics, but deployment, migrations, and durable data handling must be treated as separate operational concerns.
🔐 Auth0: Making Security Part of the Product
A financial application shouldn't treat authentication as an afterthought.
We integrated Auth0 for identity management and secure sign-in.
CashCompass supports Auth0-hosted authentication, including email/password and configured Google sign-in.
Authenticated user identity is used to scope financial data, rather than trusting client-provided account identifiers.
We use server-side session management and protected routes so users can only access financial information authorized for their account.
Two-Step Verification by Default
We also built required two-step verification into the Auth0 security experience.
Our Auth0 configuration uses its built-in multi-factor authentication policy to require an additional verification step during sign-in.
Users can enroll an authenticator app, such as Google Authenticator or Authy, to generate verification codes.
The design also supports additional configured recovery methods, including email-based backup verification and recovery codes.
The account settings interface explains the configured protection and recovery options.
One detail we particularly liked: CashCompass doesn't collect or validate MFA codes itself.
Auth0 handles that sensitive authentication workflow.
Our application focuses on authenticated sessions and user-owned financial data.
That lets us build a richer product experience while relying on a specialized identity platform for authentication security.
💳 Solana: Exploring Blockchain-Based Settlements
We also integrated a Solana devnet payment flow into Settle Up.
Users can connect supported wallets and initiate a simulated settlement workflow.
The interesting engineering challenge wasn't simply sending a transaction.
It was deciding when CashCompass should consider that transaction valid.
We implemented server-side verification that retrieves the transaction from Solana and checks its confirmation status, recipient, and transferred amount.
The server doesn't blindly trust a client-provided statement that a payment succeeded.
We also track claimed transaction signatures to reduce the risk of treating the same payment as multiple settlements.
This integration uses Solana devnet, a fixed demonstration conversion rate, and a demo recipient configuration.
It is an experimental settlement system, not a production payment platform.
But it gave us a way to explore how blockchain verification might interact with a more traditional financial ledger.
🔔 Credit Cards, Bill Reminders, and Resend
We didn't want CashCompass to stop at visualizing future bills.
We wanted it to help users remember them.
The Bills & Payments experience supports upcoming obligations, recurring bills, credit-card statement details, minimum payments, and payment tracking.
We also built configurable email reminders using Resend.
A user can choose how many days before a bill is due to receive an alert, along with a preferred hour and time zone.
The reminder system uses a scheduled server job and tracks reminder occurrences to avoid unnecessary duplicate emails.
We also support friend-related notifications and convenient WhatsApp reminder links through Settle Up.
The idea is to make CashCompass useful before a financial problem happens, not just afterward.
🎮 MoneyQuest: We Turned Financial Planning Into a Roblox Game
One of our most creative additions was CashCompass: MoneyQuest, a Roblox-based financial-literacy companion.
The concept is simple:
Can you survive 30 days without going broke?
Players enter a fictional financial neighborhood and face everyday financial decisions.
They have a limited balance, rent to pay, groceries to buy, savings to protect, and unexpected expenses to handle.
There's also a tempting $1,200 laptop.
Just like the main CashCompass application, the game challenges players to think beyond their current balance.
The experience includes a bank, store, apartment, and financial-advisor station.
Players make decisions, see their consequences, advance through a simulated month, and receive a financial-health score at the end.
Building Financial Logic in Luau
MoneyQuest isn't just a website with a game-like interface.
We created a separate Roblox Studio / Luau codebase with server-controlled financial calculations, interactive game logic, scoring, and replay.
The implementation uses a Rojo-compatible project structure so the game code can be developed and tested alongside the rest of the repository.
The financial engine uses integer-cent arithmetic, and the game avoids sharing actual banking information or authentication credentials.
Our automated Luau test suite exercises 324 complete decision paths with 4,261 assertions.
We also added a dedicated MoneyQuest page and navigation entry to CashCompass.
The Roblox game is accessed separately through its experience page, rather than pretending a Roblox world can run directly inside a Next.js iframe.
🎮 MoneyQuest: Play CashCompass MoneyQuest on Roblox
Roblox account and experience-access restrictions may apply.
☁️ Deploying CashCompass With Vultr and GoDaddy
A great hackathon application needs more than a working development server.
We wanted CashCompass to have a real home.
We deployed the Next.js application using Vultr infrastructure with Nginx, PM2, and HTTPS.
We also configured a deployment workflow that checks the main GitHub branch, builds release candidates, runs available verification checks, and supports rollback if a new release fails its health checks.
The application is available through our custom domain:
We wanted a name that was easy to remember and immediately connected to the product's purpose.
A compass gives you direction.
CashCompass gives your money direction.
🧰 The Complete Technology Stack
| Layer | Technologies |
|---|---|
| Frontend | Next.js 16, React 19, TypeScript, Tailwind CSS |
| UI and charts | Recharts, Lucide, custom design system |
| AI | Google Gemini API |
| Authentication | Auth0, MFA, protected sessions |
| Banking sandbox | Capital One Nessie API |
| Database | Tiger Data, TimescaleDB, PostgreSQL |
| Blockchain | Solana devnet, wallet adapters |
| Collaboration | DeepSpace Live Split Room |
| Notifications | Resend, WhatsApp links |
| Game development | Roblox Studio, Luau, Rojo |
| Deployment | Vultr, Nginx, PM2 |
| Domain | GoDaddy, cashcompass.club |
The most important part wasn't the number of integrations.
It was finding a meaningful responsibility for each one.
🧠 What We Learned Building CashCompass
1. AI is most powerful when grounded in reliable systems
We didn't want Gemini to manufacture financial numbers.
Separating language understanding from mathematical calculation made the experience more useful and easier to reason about.
2. Your balance is not your budget
A large account balance doesn't necessarily mean you can afford a purchase.
Future obligations and timing matter.
This was the idea that shaped nearly every feature we built.
3. Financial systems need to distinguish possibilities from facts
A planned purchase isn't a completed transaction.
An expected repayment isn't guaranteed income.
A simulated settlement isn't a real bank transfer.
Making those distinctions explicit improved both the application's behavior and the explanations users receive.
4. Collaboration adds a different layer of complexity
Splitting a receipt isn't just dividing numbers.
It involves people, expectations, payment dates, notifications, and agreement about who owes what.
Building Settle Up and exploring collaborative workflows made us think about the social side of personal finance.
5. A hackathon forces you to prioritize the story
CashCompass grew into a platform with banking, AI, blockchain, notifications, and gaming.
But the strongest way to explain it is still one simple question:
"Can I afford this MacBook today?"
That question takes users from a bank balance to a forecast, from a forecast to a decision, and from a decision to understanding its consequences.
A great demo doesn't need to show every line of code.
It needs to make someone understand why the product should exist.
🚀 What's Next for CashCompass?
There's plenty we want to explore beyond SwampHacks.
We want to expand financial forecasting, improve historical spending insights, make collaborative expense management more seamless, and strengthen banking reconciliation and persistence.
We'd also like to make the AI copilot better at explaining tradeoffs across competing goals, such as saving for a trip while managing recurring bills and unpredictable expenses.
MoneyQuest opens another interesting direction: teaching financial concepts through interactive decisions rather than passive advice.
And as we move beyond hackathon prototypes, reliability, security, transparency, and real-world testing become even more important.
Our goal isn't to make AI responsible for people's financial decisions.
It's to give people better information before they make those decisions themselves.
❤️ Final Thoughts
Building CashCompass at SwampHacks XII taught us that the most interesting products often begin with a question everyone recognizes.
"Do I have enough money?"
We realized the better question was:
"Will I still be okay after I spend it?"
That's the problem we set out to solve.
CashCompass brings together financial records, future obligations, AI assistance, simulations, and shared expenses to help users see what their money needs to do next.
Because sometimes the smartest financial decision isn't spending less.
It's knowing when to spend.
CashCompass — Your money. Your direction.
🌐 Try CashCompass: cashcompass.club
💻 GitHub: View the CashCompass repository
🎮 MoneyQuest: Play CashCompass MoneyQuest on Roblox
🤝 DeepSpace Live Split Room: Open the Live Split Room
Built with passion, plenty of debugging, and a lot of caffeine at SwampHacks XII 2026.
Top comments (0)