Add splitwise module: equal/exact/percent/share split strategies with largest-remainder paise arithmetic, derived ledger, greedy and exact debt simplification, concurrency control (13 tests, 12 transcripts)
Co-Authored-By: Claude Sonnet 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_017ic4b4aCTv6BYCer55YdjZ
This commit is contained in:
@@ -0,0 +1,57 @@
|
||||
# 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
|
||||
|
||||
```bash
|
||||
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 |
|
||||
Reference in New Issue
Block a user