BuddyBank

The intelligent way to track, share, and settle group debts.

Comment

Inspiration

We’ve all been there: the end of a fantastic group dinner or a weekend trip with friends, ruined by the awkward, tedious math of figuring out who owes what. One person pays the bill, another manually calculates taxes and tips, and suddenly the group chat is flooded with confusing "Venmo me" requests.

I realized that existing solutions either require manual data entry or don't optimize how the final debts are settled. I wanted to build a tool that eliminates the friction entirely.

What it does

BuddyBank is a smart financial utility designed to remove the friction of group living and social outings.

AI Receipt Parsing: Users simply snap a photo of a bill. The app uses a generative vision model to extract line items, taxes, and totals into a structured digital format.

Itemized Claiming: No more "splitting evenly" when one person had a salad and another had a steak. Users can claim specific items or split shared costs with a few taps.

Intelligent Debt Minimization: Instead of a chaotic web of everyone paying each other back, the app runs a custom greedy algorithm to "net" the group's finances, resulting in the absolute minimum number of transactions needed to settle up.

Group Management: Organizes expenses by trip, household, or event, providing a real-time "Net Balance" for every member.

How we built it

We designed the system using a Service-Pattern Architecture to ensure it was scalable, maintainable, and enterprise-ready.

Frontend: I built the mobile app using React Native and Expo. This file-based routing system allowed me to cleanly separate authentication flows from the main application tabs.

Backend: I chose FastAPI (Python). Since the app relies heavily on complex calculations and AI processing, a persistent, containerized Python backend was crucial to avoid "cold start" latency and handle heavy computational logic efficiently.

Database & ORM: I utilized Supabase (PostgreSQL) for the database and authentication layer. To interact with the database safely, I used SQLAlchemy ORM.

AI Parsing: When a user snaps a receipt, the image is sent to Gemini API to extract line items, prices, and taxes into structured JSON.

Debt Simplification: I implemented a custom Greedy Balance-Matching Algorithm to optimize group settlements. Instead of a naive "one-to-one" debt model, the engine calculates the Net Balance of every user and partitions the group into two sorted priority queues: Debtors (those who owe) and Creditors (those owed). By greedily matching the largest debtor with the largest creditor, the algorithm recalculates the entire debt network to ensure the group is fully settled with the absolute mathematical minimum of $N-1$ transactions.

Challenges we ran into

Building a financial utility requires absolute precision, which brought several technical hurdles:

ACID Compliance & Transactions: When a user creates an expense, multiple database tables (Expenses, Splits, and User Balances) must update simultaneously. If one fails, the whole process must roll back to prevent users from losing money. I had to deeply understand database atomicity and implement robust SQLAlchemy transaction blocks to guarantee data integrity.

Asynchronous Database Pooling: Connecting FastAPI to Supabase asynchronously was a massive learning curve. I ran into IPv6 DNS resolution errors and connection pooling conflicts between asyncpg and Supabase's internal PgBouncer. I ultimately solved this by utilizing Supabase's Session Pooler (Port 5432) alongside SQLAlchemy's native connection pool mechanism, ensuring stable and fast database queries.

Architectural Trade-offs: I initially debated calling database functions (RPCs) directly from the mobile app to save time. However, I realized that routing writes through the FastAPI middleware was necessary to securely validate complex JSON payloads and keep the business logic isolated from the frontend UI.

Accomplishments that we're proud of

Greedy Settlement Logic: Optimized group debts by matching debtors and creditors by magnitude, reducing complex transactions to the mathematical minimum of $N-1$ payments.

Full-Stack Async Architecture: I successfully built a non-blocking backend using FastAPI and SQLAlchemy 2.0 AsyncSession. This architecture allows the app to handle heavy AI processing and complex debt recalculations concurrently without degrading the user experience.

Database Integrity: Implementing atomic transactions for the settlement process was a major win. Ensuring that old debts are deleted and new optimized debts are created in a single "all-or-nothing" operation protects our users from data loss or financial discrepancies.

What we learned

Enterprise-Grade Folder Structures: Separating configuration, API routes, business logic, and database models.

Modern Python Asynchronous Programming: Managing async database dependencies and session lifecycles in FastAPI.

Algorithms in Practice: Translating abstract computer science concepts into a real-world feature that saves users time and money.

Authentication Flows: Securely managing JWTs between a mobile client, a BaaS provider (Supabase), and a custom Python backend.

What's next for BuddyBank

Venmo/ZAPI Integration: The ultimate goal is to add deep-linking, allowing users to settle their simplified debts with a single tap through their favorite payment apps.

Multi-Currency Support: Implementing real-time exchange rate APIs to help travelers split bills across different countries without manual conversion.

Social "Nudges": Developing a friendly automated notification system to gently remind group members when it's time to settle their balances.

Share this project:

Updates