chadfowler.com
Reference implementation for the Phoenix Architecture. Work in progress.
aicoding.leaflet.pub/
ai
coding
crazy
1# Settle Up — Phoenix Example
2
3An expense-splitting app (like Splitwise) specified across four specs:
4groups, expenses, settlements, and REST API.
5
6**Why this example?** It's simple enough that anyone understands it instantly —
7you split a dinner bill with friends. But it has real architectural complexity:
8money math with invariants (balances must sum to zero), a graph optimization
9problem (minimum settlements), multiple risk tiers (balance calculation is
10critical, API formatting is low), and conservation layers (the API shape
11is a public contract that can't change freely).
12
13## Walkthrough
14
15```bash
16# From the phoenix repo root (one-time)
17cd /path/to/phoenix
18npm run build && npm link
19
20# Enter this example
21cd examples/settle-up
22
23# Step 1: Initialize Phoenix
24phoenix init
25
26# Step 2: Bootstrap — ingest specs, canonicalize, plan, generate
27phoenix bootstrap
28
29# Step 3: Explore what was produced
30phoenix status # Trust dashboard
31phoenix canon # Canonical requirement graph
32phoenix plan # Implementation Units
33phoenix drift # Drift detection
34phoenix evaluate # Evidence against policy
35phoenix audit # Replacement readiness per IU
36
37# Step 4: Make a change — edit a spec, see what cascades
38# e.g. add "expenses must support tags" to spec/expenses.md
39phoenix diff # See what changed
40phoenix bootstrap # Re-run pipeline
41
42# Step 5: Install and test
43npm install
44npm test
45npm start # API server on :3000
46```
47
48## Specs
49
50| Spec | Covers |
51|------|--------|
52| `spec/groups.md` | Group lifecycle, membership, balances summing to zero |
53| `spec/expenses.md` | Expense creation, split strategies, remainder handling, balance math |
54| `spec/settlements.md` | Debt simplification algorithm, settlement recording, settled-up status |
55| `spec/api.md` | REST endpoints, error codes, response envelope, pagination |
56
57## Interesting Things to Notice
58
591. **Risk tiers vary**: Balance calculation is `critical` (money math). API formatting is `low`. Phoenix assigns different evidence requirements.
602. **Invariants are real**: "Net balances must sum to zero" is a system invariant that evaluation coverage will flag if untested.
613. **The settlement algorithm is a graph problem**: Minimum payments to settle all debts is a max-flow / net-flow optimization. Canonical extraction should identify this as a distinct requirement.
624. **The API is a conservation layer**: External clients depend on the response format. `phoenix audit` should flag it as needing conservation-layer protection.
635. **Remainder handling is subtle**: $10 split 3 ways can't be $3.33 × 3. The spec says the payer absorbs the extra cent. This is the kind of constraint that negative knowledge captures when a generation attempt gets it wrong.