MamboFinance architecture
Workspace
mambofinance-lib
-> domain values and validation
-> SQLite schema and operations
-> typed query/filter/order/update API
mambofinance-tui
-> terminal lifecycle and event loop
-> UI and widget state
-> calls mambofinance-lib
The workspace uses Rust 2024 edition. mambofinance-tui depends on the sibling library by path; the library has no dependency on the interface.
Storage model
User::new(name) opens storage/<name>.db, creates the directory when needed, enables SQLite foreign keys, and creates missing tables. User::new_in_memory(name) applies the same schema to an in-memory connection.
The schema contains:
transactions, including an integer amount, date parts, optional description, foreign keys, and an optional linked-transaction ID.groupsfor grouping ledger activity.categories, with a checked single or paired variant.fundsfor the account or store of value.currenciesreferenced by transactions.
UUID values are stored as SQLite blobs. Foreign keys cascade deletes to dependent transactions. Labels normalize names to title case and copy descriptions as supplied, while amount constructors accept any signed 64-bit integer. Date construction rejects months above 12 and days above a month's maximum, but it currently accepts day zero and can panic on month zero. Treat boundary validation as incomplete.
Ledger operations
The public User API creates and retrieves reference data, adds single or paired transactions, and exposes typed query objects. Query code supplies record-specific filtering and ordering while retaining a common wrapper for the UI.
Edit and delete operations exist in the library. Category variant changes protect linked transactions unless the caller explicitly uses the force path.
Budgets are not part of the active module tree. The empty budget placeholder does not provide a supported feature.
TUI state flow
Crossterm event
-> App update loop
-> UIState / active panel
-> sidebar, query table, or popup
-> UIEvent for a completed add form
-> User write + table refresh
Ratatui renders a sidebar, the selected query table, a contextual bottom bar, and an add popup. Completed popup fields are compiled into strings and handed to the record-specific library call.
Current prototype boundary
The binary creates User::new_in_memory("USER"), seeds currencies, funds, groups, categories, and transactions, and then starts the terminal loop. Nothing from that run is durable. Edit, delete, sort, and filter hints are visible but do not have key handlers yet.
Before a durable release, the interface still needs explicit user/database selection, input-error handling without panics, finished actions, migration/recovery policy, and an end-to-end persistence check.
Quality gates
The library's unit tests cover its current domain behavior, SQLite operations, relationships, and queries. Use the repository README's Development checks as the authoritative local sequence. The GitHub Actions workflow runs the same Cargo checks for main, tui, and pull requests targeting either branch.