refinance

refined financial system for a hackerspace. simple by design.

architecture

• entity — anything that can send or receive money: human, hackerspace, rent, fridge.
• transaction — move X from A to B. supports all currencies.
• balance — sum of all transactions from/to an entity.
• tags — for entities and transactions to perform a quick search.
• treasury - a bank account, cash box or a crypto wallet, specified in a transaction

authentication

• you can request a login link with your entity name
• login link will be sent to all available destinations (telegram, signal, email, etc) details

prod

cp secrets.env.example secrets.prod.env
make prod

API: http://0.0.0.0:8000/docs UI: http://0.0.0.0:9000

dev

environment setup (first time)

cp secrets.env.example secrets.dev.env

create local environment with all dependencies

uv python install 3.12
uv sync --dev

open project in vscode, F1 python.setInterpreter, select .venv (workspace)

if you need to change project deps:

uv add packagename
uv remove packagename
uv sync

install pre-commit hook

source ./.venv/bin/activate
pre-commit install

run backend & frontend with live code reload

make dev

open http://localhost:8000/docs and http://localhost:9000

tests

make test

todo release

• base classes
• errors
• unit tests
• complex search
• pagination
• tags
• transactions
• balances
• balance cache
• date range search
• payment splits
• multiple auth providers
• docker
• authentication?
• pytest ci
• generic deposit service
• usdt top-up
• currency exchange
• unit of work?
• fixed amount participation in split
• add split participants by a tag
• grafana, statistics
• treasuries
• logging
• postgres
• card processing

todo techdebt

• migrations
• pass tags as a list, not as add/delete operations
  • fix ui tag management
• misc validation of amounts (>0.00)
• improve split ux
• make a uniform deposit api CRUD, provider should be enum
• update all boolean attrs to status enums
• mobile ui
• rename base to common where applicable
• remove base service class

todo future features

• permissions?
• deposit ui
• donation categories (entities?)
• easy payment urls

tests notice

tests are mostly autogenerated by llm, given the route and schema. human review would be beneficial.

license

MIT