Overview

SmartWallet is an offline-first TUI application for managing personal finances. It organizes income and expenses in a hierarchical tree structure — categories can nest infinitely (e.g., Home -> Bills -> Electricity), and each leaf holds a signed transaction. The entire budget persists locally as a JSON file with schema versioning.

Built as a university project demonstrating the Composite and Factory Method design patterns with a clean MVC architecture separating business logic from the Textual-powered terminal UI.

Features

• Tree-structured budget — infinite category nesting with recursive balance calculation
• Modern TUI — custom dark theme with color-coded income/expenses
• Keyboard-driven — modal dialogs for add, edit, delete, and navigation
• Offline-first — all data stored locally in ~/.smartwallet/budget.json
• Schema versioning — safe data migrations for future releases
• 27 unit tests — full coverage of model, factory, and persistence layers

Installation

Requires uv (recommended) or pipx.

Install as a standalone CLI tool (isolated environment, added to PATH):

uv tool install smartwallet

Or with pipx:

pipx install smartwallet

Then run:

smartwallet

To upgrade or uninstall:

uv tool upgrade smartwallet    # or: pipx upgrade smartwallet
uv tool uninstall smartwallet  # or: pipx uninstall smartwallet

Local Setup (development)

1. Clone the repository:

   git clone https://github.com/alwoodm/smartwallet.git
   cd smartwallet
   

2. Install dependencies (requires uv):

   uv sync
   

3. Run the application:

   uv run smartwallet
   

Keybindings

Development

uv run ruff check .          # Lint
uv run ruff format --check . # Format check
uv run pytest                # Run tests
uv run pytest --cov          # Tests with coverage
uv build                     # Build package

Architecture

The project follows an MVC architecture with four independent modules:

For detailed documentation including design pattern analysis, see docs/architecture.md.

License

This project is licensed under the MIT license.