Expense Settlement Engine

A Python-based CLI utility to track shared group expenses and settle outstanding balances using an algorithmic cash-flow minimization technique.

Problem Statement

When groups incur shared expenses, traditional tracking leads to a high number of bilateral transfers. For N people, this can require up to N*(N-1) individual transactions.

This engine consolidates group balances into a single net ledger (Creditors vs. Debtors) and resolves payments using a Greedy Two-Pointer Algorithm, reducing total settlement transactions to at most N-1.

Features

• Object-Oriented Architecture: Clean separation of domain models (User, Expense, Split) and core algorithmic services.
• Floating-point Split Validation: Validates splits before recording to avoid fractional mismatch issues.
• Greedy Settlement: Automatically identifies the largest debtor and creditor to minimize intermediate transfers.
• Local Persistence: Stores application state locally in structured JSON format.

Project Structure

Expense_Engine/
├── models/
│   ├── user.py          # User entity definition
│   └── expense.py       # Expense and Split validation models
├── services/
│   └── settlement.py    # Net balance calculation & greedy resolution logic
├── utils/
│   └── file_handler.py  # JSON load/save operations
├── main.py              # Interactive CLI entry point
└── test_run.py          # Automated verification script