Files
..

splitwise

Companion code for the ankurm.com article Low-Level Design: Splitwise (Expense Sharing) in Java.

An expense-sharing core: four ways to split a bill (equal, exact, percent, shares) with exact paise arithmetic, a ledger derived from the expense log, and two debt simplifiers (greedy, and an exact search that finds the true minimum number of payments). Every figure and console line in the article is quoted from a file in output/, which the JUnit tests write while asserting the same numbers. There is no docs/ folder: the explanations live in the article itself.

Versions

Component Version Verified against
JDK Temurin 25.0.5+8 (LTS) java -version
JUnit 6.1.3 junit-bom maven-metadata.xml on Maven Central (latest GA)
Maven 3.9.11 mvn -version

No frameworks and no runtime dependencies: everything in src/main is plain Java.

Quickstart

cd splitwise
export JAVA_HOME=/path/to/jdk-25 PATH="$JAVA_HOME/bin:$PATH"
./scripts/run-all.sh      # runs every test and regenerates output/*.txt

The first Maven run must be online so the plugins land in the local cache. Two transcripts contain figures that depend on timing (04c-simplify-cost.txt, 06b-concurrency-control.txt); they say so in their first line and differ from run to run by design.

The pieces

Class Role
Money text to and from whole paise; the rest of the code never sees a double
Apportion largest remainder division: shares always add up to the total exactly
SplitStrategy the one interface a split implements: participants() and split(total)
EqualSplit, ExactSplit, PercentSplit, ShareSplit the four strategies; each validates its own input
Expense, Transfer, User immutable records: an expense and what each person owes, a payment, a person
Ledger net balance per person plus a per-pair view, built by applying expenses and transfers in order
Group members, the expense log, and synchronized addExpense / settle
DebtSimplifier net balances in, short list of payments out
GreedyDebtSimplifier biggest debtor pays biggest creditor; at most n - 1 payments
OptimalDebtSimplifier subset DP over zero-sum groups; the true minimum, up to 20 people
SplitwiseService registers users, creates groups

Transcripts

File Written by What it shows
01-happy-path.txt HappyPathTest a four-friend trip: shares, net balances, pairwise vs simplified debts
02-rounding.txt, 02b-rounding-property.txt RoundingTest why double and plain division fail; 200,000 seeded divisions
03-validation.txt ValidationTest eleven bad requests, the exact message for each, ledger untouched
04-simplify.txt, 04b-simplify-random.txt, 04c-simplify-cost.txt SimplifyTest where greedy is not minimal; 1,500 seeded cases cross-checked by backtracking; cost of the exact search
05-settle-up.txt, 05b-replay.txt SettleUpTest recording payments; the ledger rebuilt from the log
06-concurrency.txt, 06b-concurrency-control.txt ConcurrencyTest eight threads on one group; the same idea with an unsynchronized map
07-pitfalls.txt PitfallsTest six traps, each reproduced