🏠 FairShare AI

The intelligent roommate finance tracker that thinks before it settles.

FairShare AI is a modern Single Page Application (SPA) designed to eliminate awkward money conversations between roommates. Unlike traditional expense splitters, FairShare uses Google Gemini's Thinking Models to analyze spending habits, parse natural language inputs, and generate mathematically optimized settlement plans that minimize money transfers.

---

🚀 The Pitch: Why FairShare?

Living together is fun; splitting bills is not. Spreadsheets are error-prone, and existing apps are often rigid. FairShare AI bridges the gap between simple calculators and financial fairness.

🌟 Key Differentiators

1. 🗣️ Natural Language Entry: Don't fill out 5 form fields. Just type "I paid $45 for pizza for everyone" or "Alice paid $100 for internet split by Bob and Me". Our AI parses it instantly.
2. 🧠 "Thinking" Settlement Engine: We use Gemini 3.0 Pro to analyze the debt graph. It doesn't just do the math; it provides a Settlement Strategy, explaining why the plan is efficient and offering insights into household spending trends.
3. 🕸️ Visual Debt Graph: A dynamic, interactive graph shows exactly how money flows between roommates, making complex debts easy to visualize.
4. ⚡ Optimized Transactions: Our algorithm calculates the "Net Flow," reducing 10 circular debts into 3 simple payments.
5. 🔍 Full Transparency: A complete Audit Log tracks every edit, delete, and creation, ensuring 100% trust between users.

---

Screenshots

---

🛠️ Tech Stack

Built for speed, scalability, and UX.

• Frontend: React 19, TypeScript, Tailwind CSS
• Architecture: Single Page Application (SPA) with react-router-dom (Hash Routing)
• AI & Logic: Google GenAI SDK (gemini-2.5-flash for speed, gemini-3-pro-preview for reasoning)
• Backend / Database: Supabase (PostgreSQL)
• Security: Row Level Security (RLS) policies ensuring data privacy per house.

---

✨ Features Breakdown

1. Smart Expense Management

• Manual or AI Entry: Users can toggle between a standard form or the Smart AI input.
• Recurring Expenses: Set up rent or internet once; the system generates bills automatically (Daily/Weekly/Monthly).
• Categories: Food, Rent, Utilities, Entertainment, etc.

2. Intelligent Settlement

• Detailed Mode: See exactly who owes whom for what specific item.
• Optimized Mode: The mathematical shortest path to settle debts.
• AI Mode: Generates a summary analysis and a fair plan using generative reasoning.

3. House Management

• Multi-House Support: Users can belong to multiple houses.
• Join Codes: Simple 8-character codes to invite new roommates.
• Ghost Profiles: Add roommates who haven't signed up yet so you can start tracking immediately.

4. Robust UX

• Dark Mode: Native support.
• Responsive: Works perfectly on mobile and desktop.
• Notifications: Browser notifications for large expenses or settlement plans.

---

🚀 Getting Started

Prerequisites

• Node.js (v18+)
• A Supabase Project
• A Google Gemini API Key

Installation

1. Clone the repository

   git clone https://github.com/yourusername/fairshare-ai.git
   cd fairshare-ai

2. Install Dependencies (If using a local bundler like Vite)

   npm install

3. Environment Setup Create a .env file:

   API_KEY=your_google_gemini_api_key
   VITE_SUPABASE_URL=your_supabase_url
   VITE_SUPABASE_KEY=your_supabase_anon_key

4. Database Setup Run the SQL commands found in services/raw_sql.txt in your Supabase SQL Editor to set up Tables and RLS Policies.

5. Run

   npm run dev

---