OpenSplit

AI-powered group expense splitting — built for the way people actually travel, eat, and live together.

What It Does

OpenSplit lets groups track shared expenses and settle debts with minimal transactions using a min-cash-flow algorithm — the same approach used in Splitwise. It also ships an AI agent layer for smart features like receipt scanning, spending insights, and debt simplification.

Tech Stack

Layer	Technology
Frontend	Next.js 14 (App Router) · TypeScript · Tailwind CSS · Framer Motion
Backend	FastAPI · SQLAlchemy · Alembic · Celery + Redis
Database	PostgreSQL via Supabase
Auth	Supabase Auth · Google OAuth · JWT (RS256 + HS256)
AI Agents	LLM client abstraction layer · Background task queue
Infra	Docker Compose · multi-container orchestration

Key Features

• Real-time balance tracking — per-group and cross-group net balances (who owes whom)
• Minimum transfers algorithm — reduces N debts to the fewest possible payments
• Google OAuth — PKCE flow via Supabase, async JWT validation in FastAPI
• AI agent architecture — modular agents for receipt OCR, spending insights, debt simplification, and smart split suggestions
• Dialog-first UX — Headless UI modals, no full-page navigations for common actions
• Mobile-first — 360px minimum width, 48px touch targets, dark mode default

Architecture

frontend/          Next.js 14 App Router
backend/
  app/
    routes/        FastAPI routers (thin layer — no business logic)
    services/      Business logic (SettlementService, ExpenseService …)
    agents/        LLM agents (receipt, insights, debt simplification)
    tasks/         Celery background jobs (nudge/reminder agent)
    models/        SQLAlchemy ORM models (UUID PKs, soft delete)
    schemas/       Pydantic v2 schemas

Running Locally

# Clone and start all services
git clone https://github.com/SanoKhan22/OpenSplit
cd OpenSplit
docker compose up --build -d

# Frontend → http://localhost:3000
# Backend API → http://localhost:8000/docs

Requires a .env file — see backend/.env for the required keys (Supabase URL, anon key, JWT secret).

Design Decisions Worth Noting

• Money is always integers — stored as cents, formatted at display time only. No floats, ever.
• Async all the way — Supabase JWKS fetch and all I/O is non-blocking in FastAPI.
• Auth is stateless — middleware checks a presence cookie for SSR; actual token lives in localStorage and is sent as Authorization: Bearer on every API call.
• Currency isolation — amounts stored in the original currency; FX conversion at display time only, rates cached 1hr in Redis.

---

Made as a learning project exploring AI agent design, financial data modeling, and modern full-stack architecture.