A minimal, zero-setup shared expense-splitting and debt minimization application built with FastAPI and React + Vite + Tailwind CSS, designed as an educational reference implementation for Spec-Driven Development (SDD) with GitHub Spec Kit and AI coding agents.
┌────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ 💻 LOCAL DEVELOPER ENVIRONMENT │
│ │
│ ┌──────────────────────┐ ┌───────────────────────────────────────────────────────────────┐ │
│ │ Developer / Student │ │ 🤖 AGENTIC AI CORE │ │
│ └──────────┬───────────┘ │ │ │
│ │ Prompts │ ┌────────────────────────┐ ┌───────────────────────┐ │ │
│ ▼ │ │ Google Antigravity CLI │ ───► │ GitHub Spec Kit (CLI) │ │ │
│ ┌──────────────────────┐ │ │ ('agy') │ │ (specify-cli) │ │ │
│ │ Interactive Terminal │ ──────► │ └──────────┬─────────────┘ └───────────┬───────────┘ │ │
│ └──────────────────────┘ │ │ │ Reads/Writes │ │
│ │ │ JSON-RPC / stdio ▼ │ │
│ │ │ Tool Execution ┌──────────────────────┐ │ │
│ │ ▼ │ .specify/ & specs/ │ │ │
│ │ ┌────────────────────────┐ │ - Constitution v1.5 │ │ │
│ │ │ GitHub MCP Server │ │ - spec.md / plan.md │ │ │
│ │ │ (@modelcontextprotocol)│ │ - tasks.md │ │ │
│ │ └──────────┬─────────────┘ │ - openapi.json │ │ │
│ └──────────────┼─────────────────────┴──────────────────────┘ │ │
│ │ │ │
│ │ REST / GraphQL API │ │
│ ┌───────────────────────────────────────────────┼────────────────────────────────────────────┐ │ │
│ │ ▼ │ │ │
│ │ 📦 SPLITWISE LITE MONOREPO APPLICATION │ │ │
│ │ │ │ │
│ │ ┌───────────────────────────────────┐ ┌──────────────────────────────────┐ │ │ │
│ │ │ 🐍 FastAPI Backend (:8000) │ │ ⚛️ React + Vite UI (:5173) │ │ │ │
│ │ │ - Pydantic Invariant Validation │ ◄──────► │ - Expense Entry Form │ │ │ │
│ │ │ - In-Memory Data Store │ JSON API │ - Live Balance Sheet │ │ │ │
│ │ │ - BalanceService & DebtService │ │ - SVG Interactive Debt Graph │ │ │ │
│ │ │ - Pytest Suite (100% Math Cover) │ │ │ │ │ │
│ │ └───────────────────────────────────┘ └──────────────────────────────────┘ │ │ │
│ │ │ │ │
│ └───────────────────────────────────────────────┬────────────────────────────────────────────┘ │ │
└───────────────────────────────────────────────────┼────────────────────────────────────────────────────┘
│ git push (Feature Branch / PR)
▼
┌────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ ☁️ GITHUB CLOUD & GOVERNANCE PLATFORM │
│ │
│ ┌────────────────────────────────────────────────────────────────────────────────────────────────┐ │
│ │ 🐙 Remote Repository (juanireil/spec-kit-test-splitwise) │ │
│ │ - Protected 'main' Branch (Direct Pushes Blocked) │ │
│ │ - Tracked GitHub Issues & Bidirectional Traceability Matrix (RTM) │ │
│ └──────────────────────┬─────────────────────────────────────────────────┬───────────────────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────────────────────────────────────┐ ┌──────────────────────────────────────────────┐ │
│ │ ⚙️ GitHub Actions CI Pipeline │ │ 🤖 GitHub Copilot Code Review │ │
│ │ 1. Backend: Ruff Linter & Pytest Coverage │ │ - Automated PR Code-Level Evaluation │ │
│ │ 2. Frontend: Production Build Check │ │ - Strict Check on Precision, Safety & Math │ │
│ │ Status Gate: 100% Green Required to Merge │ │ │ │
│ └─────────────────────────────────────────────┘ └──────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────────────────────────────────────────────────┘
For instructors, teaching assistants, and students, refer to these dedicated documentation guides:
-
🛠️ Repository & Environment Setup Guide:
- System prerequisites (
Python 3.10+,uv,Node.js 18+,npx). - Installing Google Antigravity CLI (
agy) and configuring the GitHub MCP Server. - Spec Kit installation and project initialization.
- Setting up Automated CI/CD Pipelines (
.github/workflows/ci.yml), Branch Protection Rules, and Copilot Code Reviews.
- System prerequisites (
-
🎓 60-Minute Class & Live Demo Guide:
- Complete 60-minute practical lesson roadmap with timing breakdowns.
- 10 Core Spec Kit Commands Reference with prompt examples and DO/DON'T rules.
- 3 Golden Rules & 4 Anti-Patterns of Agentic Pair Programming.
- Step-by-step live demo script (Specifying, Planning, TDD Implementation, PR Review, and Green CI/CD Gating).
- In-depth appendix on Spec Kit Presets and Extensions (
assess&bug).
-
- Ready-to-copy prompts for the live class demonstration (Unequal / Custom Expense Splits).
-
- How to bridge Lean Inception User Story Maps into actionable feature specifications (
/speckit-specify). - Sprint routine for teams of 6 developers running 3 parallel pairs.
- Vertical domain slicing, OpenAPI contract mocking, and directory collision prevention.
- Student Pull Request governance checklist.
- How to bridge Lean Inception User Story Maps into actionable feature specifications (
-
- Non-negotiable engineering principles, mathematical conservation invariants, and formal Definition of Ready (DoR) and Definition of Done (DoD) quality gates.
-
Iteration 01 (MVP) - Expense Tracking & Live Balances:
- Record shared expenses with equal splitting and exact fractional cent distribution.
- Live balance sheet computing net financial positions (
Total Paid - Total Owed). - Strict preservation of the zero-sum group conservation invariant ($\sum \text{Balances} =
$0.00$ ).
-
Iteration 02 - Debt Minimization Engine & Visual Graphs:
- Greedy settlement minimization algorithm reducing debts to at most
$N - 1$ direct transactions. - Interactive SVG-based directed graph rendering nodes (debtors in red, creditors in green) and payment arrows with exact dollar badges.
- Real-time automatic recalculation and graph re-rendering upon expense creation.
- Greedy settlement minimization algorithm reducing debts to at most
-
Iteration 03 - Unequal / Custom Expense Splits (Exact Amounts & Percentages):
- Supports 3 split modes: Equal, Exact Amounts ($), and Percentages (%).
- Enforces strict mathematical invariants:
$\sum \text{Shares} \equiv \text{Expense Total}$ with deterministic fractional-cent remainder distribution. - Real-time interactive split validation and dynamic remainder calculation on both client and server.
To explore further iterations during course sprints, student teams can tackle:
- Category Tagging & Spending Breakdown:
- Tag expenses with visual categories (Food, Transport, Entertainment, Utilities).
- Category filtering pills and dynamic percentage spending breakdown progress bars.
- Direct Debt "Settle Up" & Payment Recording:
- Interactive payment execution directly from graph edges to record partial or full debt payoffs.
- Multi-Currency Support & Live FX Conversion:
- Record expenses in foreign currencies with deterministic exchange rate conversions.
- Activity Search, Date Filtering & CSV/JSON Export:
- Search by keyword, date-range filters, and downloadable financial audit reports.
# In repository root
pip install -r backend/requirements.txt
python3 -m uvicorn backend.src.main:app --reload --port 8000Interactive API documentation: http://localhost:8000/docs.
cd frontend
npm install
npm run devOpen http://localhost:5173 in your browser.
Run the full backend test suite with coverage enforcement:
python3 -m pytest backend/tests --cov=backend/src --cov-report=term-missingTest Status: 23/23 tests passing with 100% path coverage on core math (balance_service.py and debt_service.py).
Run the Ruff linter:
ruff check backend