SplitUp 💸

A full-stack, Splitwise-style expense-sharing app for splitting trip and group costs with friends — with multi-payer expenses, three split algorithms, real-time balance netting, Google sign-in, and email invites.

🔗 Live demo: https://<your-vercel-url>.vercel.app · API: splitup-yxut.onrender.com/api/health

---

Table of contents

• What it does
• Why it's interesting (technical highlights)
• Tech stack
• Architecture
• The money engine
• Data model
• Security
• API overview
• Local setup
• Testing
• Deployment
• Project layout

---

What it does

SplitUp lets a group of people track shared spending and figure out who owes whom, without spreadsheets or manual arithmetic.

• Groups & friends — create a group with a shareable join code / QR, or track one-on-one expenses directly with a friend (no group required).
• Add an expense with a description, amount, date, one or multiple payers, and a split across any subset of members.
• Three split modes — split equally, by exact amounts, or by percentage / shares.
• Live balances — the app nets every expense and payment into a single "you are owed / you owe" figure per person, per group and overall.
• Settle up — record a payment between two members; balances move toward zero and both parties get a notification.
• Activity feed — a per-user notification stream (dismissible independently by each side).
• Auth — email/password and Google Sign-In, with password reset and email-based group/friend invitations.

---

Why it's interesting (technical highlights)

A few things that go beyond a standard CRUD app:

• Shared money-math module used by both client and server. The split/balance algorithms live in a framework-agnostic /shared package imported by the React frontend (for instant live previews) and the Express backend (as the authoritative recompute). The preview a user sees is guaranteed to match what gets stored, because it's literally the same code.
• All money is integer paise — never floats. Every amount is stored and computed as integer hundredths of a rupee, eliminating an entire class of floating-point rounding bugs. Conversions round explicitly rather than relying on parseFloat(x) * 100.
• Exact splits via the largest-remainder (Hamilton) method. Percentage and share splits distribute leftover paise to the largest fractional remainders, so per-person amounts always sum exactly to the total — no lost or phantom paise.
• Multi-payer expenses. An expense can be fronted by several people at once; balances are computed from the actual money each person paid vs. their resolved share.
• A defended zero-sum invariant. The group balance engine asserts that the sum of every member's balance is exactly 0 — every paise owed by someone is owed to someone. A broken invariant throws instead of silently corrupting balances.
• Unit-tested core. The split, pairwise, and balance logic is covered by ~50 tests using Node's built-in node:test runner.

---

Tech stack

Frontend

Concern	Choice
UI library	React 19
Build tool / dev server	Vite 8 (dev proxy to the API, no CORS setup needed locally)
Styling	Tailwind CSS 4 (via @tailwindcss/vite), Inter font, Material Symbols
Server state / caching	TanStack React Query
Routing	React Router 7 (route guards for protected / public-only routes)
Local/UI state	React Context (auth, toasts, expense-form wizard)
HTTP	Axios (single configured instance, cookies sent with every request)
Extras	QR code generation for group invites
Linting	oxlint

Backend

Concern	Choice
Runtime / framework	Node.js (ESM) + Express 5
ORM	Prisma 7 with the Neon serverless adapter
Database	PostgreSQL (Neon, serverless)
Auth	JWT in an httpOnly cookie (Bearer-header fallback for tooling)
Passwords	bcryptjs hashing
OAuth	Google Sign-In via google-auth-library
Email	Nodemailer (Gmail SMTP) for resets & invites
Middleware	cors (credentialed allowlist), cookie-parser, dotenv

Tooling & infra

Monorepo run with concurrently · Prisma Migrate (14 versioned migrations) · deployed on Vercel (frontend) + Render (API) + Neon (database).

---

Architecture

┌──────────────────────────┐        ┌───────────────────────────┐
│   Client (Vercel)        │        │   API (Render)            │
│   React 19 + Vite +      │  HTTPS │   Express 5 (ESM)         │
│   Tailwind + React Query │ ─────► │   REST /api/*             │
│                          │ cookie │   JWT (httpOnly) auth      │
│   axios (withCredentials)│ ◄───── │   Prisma 7                │
└───────────┬──────────────┘        └────────────┬──────────────┘
            │                                     │
            │        imports the same             │  Neon serverless adapter
            ▼        /shared money module         ▼
      ┌─────────────────────────┐          ┌──────────────────┐
      │  shared/ (pure JS)      │          │  PostgreSQL      │
      │  splitMath · balances · │          │  (Neon)          │
      │  pairwise  (+ tests)    │          └──────────────────┘
      └─────────────────────────┘

The backend follows a clean routes → controllers → utils layering, with a single requireAuth middleware gatekeeping protected routes. Prisma is the single source of truth for the schema; migrations are versioned and committed.

---

The money engine

The /shared module is the core of the app and is deliberately UI- and DB-agnostic.

splitMath.js — resolves any expense into canonical per-person shares that sum exactly to the total:

• splitEqually — divides evenly and hands leftover paise to the first N participants deterministically (10000 / 3 → [3334, 3333, 3333]).
• splitExact — passes through caller-supplied amounts (validated to sum correctly).
• splitByWeights — percentage/shares split using the largest-remainder method so paise always reconcile.
• validateSplit — rejects negative shares and reports human-readable over/short amounts.
• rupeesToPaise / paiseToRupees — safe, rounding-correct conversions.

balances.js — nets an entire group into one signed balance per member (credit each payer what they fronted, debit each participant their share, then apply settlements), and asserts the sum-to-zero invariant.

pairwise.js — computes the one-on-one "friend view": how much one specific person owes another from a single expense, correctly attributing multi-payer contributions.

---

Data model

12 Prisma models backing a normalized PostgreSQL schema. Highlights:

• User — supports both password and Google accounts (nullable passwordHash, unique googleId).
• Group + GroupMember — many-to-many membership via a join table, each group with a unique join code.
• Expense with ExpensePayment (multi-payer) and ExpenseShare (per-person owed amount). A nullable groupId models Splitwise-style direct expenses between two friends.
• Settlement — a payment from one member to another that moves both balances toward zero.
• Friendship — a single directed row per pair with pending / accepted status.
• Activity — a denormalized, per-user notification feed; one payment writes two rows so each side can dismiss independently without affecting balances.
• PasswordResetToken & Invitation — store only the SHA-256 hash of the emailed token, with expiry and single-use semantics.

---

Security

• Passwords hashed with bcrypt; never stored or logged in plaintext.
• JWTs live in httpOnly cookies (not localStorage), reducing XSS token theft. In production the cookie is Secure + SameSite=None to work across the Vercel/Render origins.
• Reset & invite tokens are emailed as raw secrets but persisted only as SHA-256 hashes, with short expiry, single-use enforcement, and email-locking — a database leak can't forge a working link.
• CORS uses an explicit credentialed origin allowlist (no wildcard, which is invalid with credentials anyway).
• Google tokens are verified server-side against the app's own client ID.

---

API overview

A REST API of ~40 endpoints under /api, grouped by feature:

Router	Responsibilities
/api/auth	register, login, Google sign-in, logout, forgot/reset password, get/update profile
/api/groups	create/list/get/update/delete, join, leave, invite (code + email), members, expenses, balances, settlements
/api/expenses	get / edit / delete a single expense
/api/friends	list, request/accept/decline/remove, email invite, per-friend expenses & settlements
/api/settlements	delete a settlement
/api/invitations	fetch & accept an emailed invite by token
/api/activity	fetch & dismiss notifications

A /api/health endpoint reports liveness.

---

Local setup

Prerequisites: Node.js (with npm) and a free Neon Postgres project.

# 1. Install root, server, and client dependencies
npm run install:all

# 2. Configure the backend
cp server/.env.example server/.env
#   → set DATABASE_URL & DIRECT_URL (Neon), JWT_SECRET, GOOGLE_CLIENT_ID,
#     Gmail SMTP creds, and CLIENT_URL

# 3. (Optional) configure the frontend
cp client/.env.example client/.env.local   # leave VITE_API_URL unset for local dev

# 4. Create the database tables
cd server && npx prisma migrate dev && cd ..

# 5. Run backend + frontend together
npm run dev

• Frontend → http://localhost:5173
• Backend → http://localhost:5000

In dev, Vite proxies /api/* to the backend, so there's no CORS configuration to worry about locally.

---

Testing

The money-critical logic is unit-tested with Node's built-in test runner:

npm test

Covers equal / exact / percentage splits, rounding and remainder distribution, pairwise friend balances, and the group-level sum-to-zero invariant.

---

Deployment

Layer	Host	Notes
Frontend	Vercel	SPA rewrite in vercel.json; VITE_API_URL points the build at the Render API
Backend	Render	Express server; COOKIE_SECURE=true for cross-origin auth cookies
Database	Neon	Serverless Postgres; migrations applied via Prisma

---

Project layout

.
├── client/          # React 19 + Vite + Tailwind frontend
│   └── src/
│       ├── api/         # axios instance + typed API wrappers
│       ├── components/  # auth, expense, group, layout, ui
│       ├── context/     # Auth / Toast / ExpenseForm providers
│       ├── lib/         # formatting, datetime, balance helpers
│       └── pages/       # route-level screens
├── server/          # Express 5 API
│   ├── prisma/          # schema + 14 versioned migrations
│   └── src/
│       ├── controllers/ # auth, group, expense, settlement, friend, invitation
│       ├── routes/      # feature routers
│       ├── middleware/  # requireAuth (JWT gatekeeper)
│       ├── utils/       # jwt, password, email, tokens, join codes
│       └── index.js     # app entry
├── shared/          # framework-agnostic money engine (+ tests)
│   ├── splitMath.js
│   ├── balances.js
│   └── pairwise.js
└── package.json     # monorepo scripts (runs both apps together)

---

_{Built with React, Express, Prisma, and PostgreSQL. Money handled in integer paise, because floats and money don't mix.}