LedgerBase is a modular financial transaction classification and budgeting platform designed for centralized, transparent, and analyzable financial recordkeeping. Built with modern Python practices and cloud-native tools, it supports multi-account imports, vendor classification, budget tracking, and reconciliation with actual savings.
| Workflow | Status |
|---|---|
| Bandit |  |
| pip-audit |  |
| Semgrep |  |
| Snyk |  |
| Trivy |  |
| Safety |  |
Repository Scorecard:
- Python 3.12+
- Poetry – Dependency management
- Flask – Backend API framework
- PostgreSQL – Primary data store
- Docker Compose – Container orchestration
- GitHub Actions – CI/CD
- Bandit, Flake8, Mypy, Black, Isort – Code quality and security checks
- ETL pipeline for importing and normalizing transactions
- Vendor dictionary with regex-based classification
- Budgeting system with historical and savings-based models
- Person-level tagging for family member analysis
- Reimbursement and savings account reconciliation
- Modular service structure for maintainability
- Python 3.12+
- Docker & Docker Compose
- Poetry (
pip install poetry)
git clone https://github.com/williaby/ledgerbase.git
cd ledgerbasepoetry installpoetry run flask runFor detailed setup and architecture, see docs/setup-instructions.md.
poetry run pytest
poetry run flake8
poetry run bandit -r src
poetry run mypy srcOr run everything with:
pre-commit run --all-filesNote: Ensure
pre-commitis installed and initialized:poetry run pre-commit install
The project integrates static security analysis via:
Bandit– Python vulnerability scanningTrivy– Docker image scanningSnyk– Dependency vulnerability scanningdetect-secrets– Secret leak prevention
The codebase uses a modular layout under src/ledgerbase/. Each service (e.g.,
plaid_service, etl, security) follows single responsibility principles.
docker-compose up --buildUse the included Dockerfile in src/flask/ for Flask containerization.
We welcome contributions and suggestions! To get started:
- Fork the repo
- Create your branch:
git checkout -b feature/xyz - Commit your changes:
git commit -am 'Add xyz' - Push to the branch:
git push origin feature/xyz - Create a pull request
Please ensure you run the full pre-commit suite and tests before submitting PRs.
MIT License. See LICENSE for details.
Byron Williams CPA GitHub: @williaby