💸 SplitSmart

An AI-powered expense splitter app built with React, TypeScript, and Tailwind CSS.
Split bills with friends — equally, by item, or by percentage — in seconds.

---

✨ Features

• 3 Split Modes — Equal split, item-based assignment, or custom percentage
• AI Bill Parsing — Paste a bill as text or snap a photo and let Gemini AI extract items automatically
• Group Management — Save your regular squads and load them instantly for future splits
• Expense History — Track all past settlements, mark payments as done, and filter by group
• Smart Settlement Algorithm — Minimizes the number of transactions between people
• LocalStorage Persistence — Your groups and history survive browser refreshes
• Confetti on Settlement — Because splitting bills should feel good 🎉
• Responsive UI — Works beautifully on mobile and desktop

---

🖥️ Demo

Live App: splitsmart-expense.vercel.app

---

🛠️ Tech Stack

Technology	Purpose
React 19 + TypeScript	UI and state management
Tailwind CSS v4	Styling
Vite 6	Build tool
Framer Motion	Animations
Gemini AI (Google)	AI bill parsing
canvas-confetti	Settlement celebration
Lucide React	Icons
Vercel Functions	Serverless API (production)

---

🧑‍💻 React Concepts Covered

• useState for all app state
• useEffect for localStorage sync
• useMemo for derived calculations
• Component-based architecture with props
• Conditional rendering and dynamic lists
• Form handling and user input
• LocalStorage persistence

---

🚀 Getting Started

Prerequisites

• Node.js 18+
• A free Gemini API key

Local Setup

1. Clone the repository

git clone https://github.com/YOUR_USERNAME/splitsmart.git
cd splitsmart

2. Install dependencies

npm install

3. Set up environment variables

cp .env.example .env

Open .env and add your Gemini API key:

GEMINI_API_KEY=your_gemini_api_key_here

4. Start the development server

npm run dev

Open http://localhost:3000 in your browser.

Note: The AI bill parsing feature requires a valid GEMINI_API_KEY. Manual entry of bill items works without a key.

---

☁️ Deploy to Vercel

1. Push your code to GitHub (see GitHub setup below)

2. Go to vercel.com → Import Project

3. Connect your GitHub repo

4. Add environment variable

In Vercel project settings → Environment Variables:

Name:  GEMINI_API_KEY
Value: your_gemini_api_key_here

5. Deploy — Vercel auto-detects Vite and deploys. Your app is live! 🎉

---

📁 Project Structure

splitsmart/
├── api/
│   └── parse-bill.ts        # Vercel serverless function (Gemini AI proxy)
├── src/
│   ├── App.tsx              # Main app component
│   ├── main.tsx             # React entry point
│   ├── index.css            # Global styles
│   ├── types.ts             # TypeScript interfaces
│   ├── services/
│   │   └── aiService.ts     # API client
│   └── utils/
│       └── algorithm.ts     # Settlement algorithm
├── public/
├── server.ts                # Express dev server (local only)
├── vercel.json              # Vercel deployment config
├── vite.config.ts
└── package.json

---

🤝 How to Use

1. Add bill items — paste text, scan a photo, or add manually
2. Add people — enter names or load a saved group
3. Choose split mode — Equal / Item-based / Percentage
4. Settle up — see who owes what with minimum transactions

---

🧮 Settlement Algorithm

Uses a greedy approach to minimize transactions:

1. Calculate each person's net balance (paid − consumed)
2. Sort debtors and creditors
3. Greedily match largest debtor with largest creditor
4. Repeat until settled

---

📄 License

MIT License — see LICENSE for details.

---

🙏 Acknowledgements

• Part of 100+ React JS Projects
• AI powered by Google Gemini
• Icons by Lucide

---

Made with ❤️ · Star ⭐ this repo if it helped you!