Finance mosaix is a DuckDB-based personal finance application for importing Excel transaction sheets, tracking cash flow, monitoring assets, and visualizing results with a Streamlit dashboard.
Disclaimer: this project was mainly realized with CoPilot assistance, using the Raptor mini model for content generation and implementation guidance.
src/: core finance logic, database schema, import and query helpersdashboard/: Streamlit dashboard UI, charts, and data viewstest/: automated tests for import logic and queriesdocs/: project-specific documentation and usage guidesCONTRIBUTING.md: contribution guidelinesLICENSE: MIT license
- Public brand name:
Finance mosaix - Internal code/package name:
FinanceMosaix - Project root folder:
finance-mosaix/ - The virtual environment is created under
finance-mosaix/.venv.
Finance mosaix is named for the way it brings many finance data pieces together into a single, structured view. It combines budgets, cash flow, assets, reports, and transaction history into one coherent, dynamic picture.
- Create a Python virtual environment in the project root:
python -m venv .venv
.\.venv\Scripts\activate- Install the package and runtime dependencies:
python -m pip install --upgrade pip
python -m pip install .- Generate a sample database with realistic data:
python create_sample_database.pyThis creates finance_sample.duckdb in the current project directory.
- Start the dashboard:
python start_dashboard.py- Open the URL shown by Streamlit to view charts and reports.
The sample database includes:
- checking, savings, and brokerage accounts
- income and expense transactions
- stock portfolio snapshots
- goods depreciation valuations
- interest account balance changes
This dataset is suitable for taking a dashboard screenshot or exploring the app immediately.
From the project root:
python src/finance_cli.py --init
python src/finance_cli.py --import path/to/file.xlsx
python src/finance_cli.py --balance
python src/finance_cli.py --spending 30
python src/finance_cli.py --search "rent"More detailed documentation is available in docs/:
This project is licensed under the MIT License. See LICENSE for details.