🚀 SplitSmart

AI-Powered Smart Expense Splitter

SplitSmart is a customer-facing smart expense splitting application. It enables users to manage shared expenses, calculate balances, generate settle-up suggestions, and leverage AI for natural language expense parsing and restaurant bill parsing.

---

✨ Features

👥 Group Management

• Create expense groups
• Seeded demo users
• Switch between users
• Automatic group filtering

💸 Expense Management

• Manual expense entry
• Server-side validation using Pydantic
• Multiple split methods:
  • Equal (All Members)
  • Equal (Selected Members)
  • Custom Amount
  • Weighted Share

📊 Smart Balance Calculation

• Real-time balance calculation
• Minimum-transfer settlement algorithm
• Clear creditor/debtor overview

📜 Expense History

• View complete expense history
• Search expenses
• Filter by:
  • Date range
  • Payer
  • Text search

🤖 AI Features

• Natural language expense parsing
• Restaurant bill text parsing
• Assignable line items
• Structured AI responses
• Draft review before confirmation
• Graceful fallback when AI is unavailable or confidence is low

🧪 Testing

• Unit tests
• API smoke tests

---

🛠 Tech Stack

Layer	Technology
Backend	Flask
Validation	Pydantic
Database	SQLite
Frontend	HTML, CSS, JavaScript
AI	Gemini Responses API

---

📂 Project Structure

SplitSmart_Smart_Expense_Splitter/
│
├── client/
│   ├── static/
│   └── templates/
│
├── server/
│
├── smart_expense_splitter_full_code/
│   ├── app.py
│   ├── requirements.txt
│   ├── data/
│   ├── models/
│   ├── routes/
│   ├── services/
│   ├── schemas/
│   ├── static/
│   ├── templates/
│   ├── tests/
│   └── utils/
│
├── templates/
│
├── .env
├── .gitignore
├── ARCHITECTURE.md
├── PROMPTS.md
├── README.md
├── server.err.log
└── server.out.log

Directory names may vary slightly depending on your project organization.

---

✅ What Works

Core Functionality

• ✅ Group creation
• ✅ Seeded demo users
• ✅ User switcher
• ✅ Group filtering
• ✅ Manual expense creation
• ✅ Expense validation
• ✅ Equal split
• ✅ Equal subset split
• ✅ Custom amount split
• ✅ Weighted share split
• ✅ Group balance calculation
• ✅ Settle-up suggestions
• ✅ Expense history
• ✅ Expense search
• ✅ Date filtering
• ✅ Payer filtering

AI Features

• ✅ Natural-language expense parsing
• ✅ Restaurant bill text parsing
• ✅ Line-item assignment
• ✅ Draft generation before saving
• ✅ AI confidence handling
• ✅ Graceful fallback when API key is unavailable

Database

• ✅ SQLite integration
• ✅ Automatic database creation
• ✅ Seeded data
  • 3 Groups
  • 8 Users
  • 24 Expenses

Quality

• ✅ Unit Tests
• ✅ API Smoke Tests

---

🚧 Not Implemented Yet

The following enhancements are intentionally left out for the assessment scope.

• Image OCR for bill photos
• Live multi-user synchronization
• Multi-currency conversion
• CSV export
• PDF export
• Recurring expenses
• Activity feed

---

⚙️ Installation

1. Clone the repository

git clone <repository-url>
cd SplitSmart

---

2. Install dependencies

pip install -r requirements.txt

---

3. Configure AI (Optional)

To enable AI-powered expense parsing, configure your Gemini API key.

Windows PowerShell

$env:GEMINI_API_KEY="your_key_here"

Linux / macOS

export GEMINI_API_KEY="your_key_here"

If no API key is provided, SplitSmart automatically switches to graceful fallback mode.

---

4. Run the application

python app.py

Open your browser:

http://127.0.0.1:5000

On the first run the application will automatically:

• Create the SQLite database
• Generate all required tables
• Seed demo users
• Seed demo groups
• Seed demo expenses

---

🧪 Running Tests

Run all tests using:

python -m unittest discover -s tests -v

---

🌐 API Overview

Users

GET    /api/users/
POST   /api/users/

---

Groups

GET    /api/groups/
POST   /api/groups/
GET    /api/groups/<group_id>

---

Expenses

GET    /api/groups/<group_id>/expenses
POST   /api/groups/<group_id>/expenses

---

Balances

GET    /api/groups/<group_id>/balances

---

Settlements

GET    /api/groups/<group_id>/settlements

---

AI Endpoints

Parse Natural Language Expense

POST /api/groups/<group_id>/ai/parse-expense

Parse Restaurant Bill

POST /api/groups/<group_id>/ai/parse-bill

---

💾 Database

SplitSmart uses SQLite as its database.

The database file is automatically created at:

data/expense_splitter.db

Money Handling

To avoid floating-point precision issues:

• All monetary values are stored as integer paise
• No floating-point currency values are persisted

---

🤖 AI Workflow

The AI integration follows a safe review-first workflow.

User Input
      │
      ▼
 Gemini API
      │
      ▼
 Structured Parsing
      │
      ▼
 Draft Generation
      │
      ▼
 User Review
      │
      ▼
 Confirm Expense
      │
      ▼
 Save to Database

Important:

• AI output is never directly stored
• Every AI response becomes a reviewable draft
• Users must explicitly confirm before data is saved

---

📌 Notes

• Single-command setup
• No frontend build process
• No external database configuration
• SQLite-based persistence
• Interview-friendly architecture
• Lightweight deployment
• AI features degrade gracefully when unavailable

---

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

---

⭐ If you found this project interesting, consider giving it a star!

SplitSmart
A Smart AI-Powered Expense Splitting Platform

Designed and Developed by Vaishnavi Misal

🚀 Deployment

The application is deployed on Render and can be accessed using the live URL below.

Hosting Platform: Render Live Application: https://splitsmart-smart-expense-splitter.onrender.com