refinance

refined financial system for a hackerspace. simple by design.

architecture

entity

anything that can send or receive money: human, donate-box, rent, utility.

transaction

move X from A to B. supports all currencies.

• non-confirmed
• confirmed

balance

sum of all transactions. both confirmed and not. separated.

tags

mark entities and transactions for quick search.

authentication

• you can request a login link with your entity name, telegram id, signal id or whatever.
• login link will be sent to all available destinations (telegram, signal, email, etc)
• new login link does not revoke old ones, so no one can deauthenticate you.

OpenID Connect (OIDC) setup

To enable OIDC-based login alongside Telegram:

1. Add these environment variables (e.g. in secrets.env or your shell):

   export REFINANCE_OIDC_CLIENT_ID=<your-client-id>
   export REFINANCE_OIDC_CLIENT_SECRET=<your-client-secret>
   export REFINANCE_OIDC_DISCOVERY_URL=https://your-oidc-provider/.well-known/openid-configuration
   export REFINANCE_OIDC_REDIRECT_URI=http://localhost:8000/auth/oidc/callback

2. Restart the backend service.

3. Navigate your browser to GET /auth/oidc/login to begin the OIDC flow.

4. After successful authentication, you will be redirected to the UI with a valid token at /auth/token/<token>.

5. Use this token to access any protected API endpoint as usual.

production

put secrets into secrets.env. see secrets.env.example as a reference.

make prod-daemon

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

development

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

tests

make test

run backend & frontend with live code reload

make dev

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

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

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 _in and _out postfixes for entities not needed
• remove base service class

todo future features

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

tests notice

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

license

MIT