commit 6ec131f34d96a52173e01e3f95f5c9cc79b6a382 Author: zemion Date: Mon Jul 6 14:38:40 2026 +0200 Sync Repo-README from project files diff --git a/Repo-README.-.md b/Repo-README.-.md new file mode 100644 index 0000000..88bd1b4 --- /dev/null +++ b/Repo-README.-.md @@ -0,0 +1,223 @@ + + +> Mirrored from `/mnt/DATA/git/mousehold/README.md`. +> Origin: `repository`. +> Active tasks and changing state belong in Gitea issues; this wiki page is durable project context. + +--- +# Mousehold + +Household finance ledger scaffold for an evidence-driven household budget and settlement system. + +The first milestone is a local proof of concept: + +- Python/FastAPI backend with SQLite by default. +- React/Vite web app. +- Local-agent scaffold for bank, CSV, statement, and IMAP ingestion. +- Raw observations become candidate, announced, outstanding, or confirmed financial events. +- Settlement and project summaries are calculated from confirmed ledger state. + +## Run + +```sh +python -m venv .venv +. .venv/bin/activate +pip install -r requirements-dev.txt +pip install -e . +mousehold-api +``` + +In another shell: + +```sh +npm install +npm run dev:web +``` + +Open `http://127.0.0.1:5173`. + +The API listens on `http://127.0.0.1:8000` and exposes OpenAPI at `/docs`. +If `8000` is already occupied: + +```sh +uvicorn mousehold_api.main:app --host 127.0.0.1 --port 8001 +cd apps/web +VITE_API_URL=http://127.0.0.1:8001 npm run dev -- --host 127.0.0.1 --port 5173 +``` + +Or start both processes with matching local-dev CORS settings: + +```sh +scripts/launch-dev.sh +``` + +## MVP workflow + +Use `Setup` to create a household, users, accounts, and connector profiles. The +top bar has a `Signed in` selector; choosing a user creates a local session +cookie for that browser. This is passwordless local-session support for the +self-hosted MVP, not a hosted multi-tenant auth system. + +Create FinTS, IMAP, or CSV/statement connector profiles in `Setup` before using +the `Bank`, `Mail`, or `Statements` pages. Those pages use the saved profile for +defaults and import attribution, while PIN/TAN, IMAP password, and selected CSV +files stay ephemeral. + +Use `Inbox` after manual entry or imports to review source observations. You can +keep an observation, confirm its linked event, ignore just the observation, +ignore the linked event too, or link the observation to an existing ledger event. +Use `Import runs` on the dashboard or connector pages to see imported, +duplicate, and event counts from each sync. + +Use `Setup -> Backup` to export the household as JSON or create a local SQLite +backup file. + +Browser-driven FinTS access is embedded in the API under `/agent/fints/...`. +Use the `FinTS` panel in the web app. PIN/TAN inputs go to the API process you +are running locally or self-hosting; normalized observations are imported into +the ledger only when you click import. + +For comdirect, choose the `comdirect` preset in the FinTS panel. Enter your +comdirect Zugangsnummer as the bank user ID, leave customer ID empty, and enter +your registered FinTS product ID. + +IMAP access is embedded under `/agent/imap/...` and available from the `Mail` +panel. Enter the IMAP host, login, app password, folder, and filters, then list +folders or scan. The scan uses a read-only folder selection and stages parsed +messages in the browser. Ledger observations are stored only when you click +import. + +Use the `Statements` panel for PayPal Activity Download CSV files and Klarna CSV +statements. It previews rows in the browser and imports them as `paypal_csv` or +`klarna_csv` confirmation evidence. + +Use the `Reconcile` panel after imports to find likely links between early mail +evidence, PayPal/Klarna statement rows, and bank/FinTS cash movement. Accepting a +suggestion links the evidence and can upgrade the original announced/outstanding +event to confirmed. + +## Local Agent + +Register a local agent after creating a household and user: + +```sh +mousehold-agent register \ + --household-id \ + --owner-user-id +``` + +Import demo observations: + +```sh +mousehold-agent sync-demo \ + --connection-id \ + --household-id \ + --owner-user-id \ + --source-account-id +``` + +Import bank or PayPal CSV: + +```sh +mousehold-agent sync-csv \ + --connection-id \ + --household-id \ + --owner-user-id \ + --source-account-id \ + --source-type bank_csv \ + --path ./transactions.csv +``` + +Discover FinTS accounts locally: + +```sh +mousehold-agent fints-accounts \ + --profile my-bank \ + --blz \ + --server \ + --bank-user-id \ + --with-balances +``` + +Display recent FinTS transactions locally: + +```sh +mousehold-agent fints-transactions \ + --profile my-bank \ + --blz \ + --server \ + --bank-user-id \ + --iban \ + --days 30 +``` + +Import FinTS transactions into the ledger: + +```sh +mousehold-agent sync-fints \ + --api-url http://127.0.0.1:8001 \ + --connection-id \ + --household-id \ + --owner-user-id \ + --source-account-id \ + --profile my-bank \ + --blz \ + --server \ + --bank-user-id \ + --iban \ + --days 30 \ + --display +``` + +The FinTS connector prompts for the PIN if `MOUSEHOLD_FINTS_PIN` or `--pin` is +not supplied. TAN mechanism and TAN medium selection are handled interactively +and cached under `~/.config/mousehold/fints/.json`; the cache does not +store the PIN. + +You can also run the FinTS browser bridge as a separate local-only process: + +```sh +mousehold-agent serve --host 127.0.0.1 --port 8765 +``` + +Set `VITE_LOCAL_AGENT_URL=http://127.0.0.1:8765` in `apps/web/.env.development` +if you choose this mode. + +CLI IMAP scanning can still use local environment variables: + +```sh +MOUSEHOLD_IMAP_HOST=imap.example.com +MOUSEHOLD_IMAP_USERNAME=you@example.com +MOUSEHOLD_IMAP_PASSWORD=app-password +MOUSEHOLD_IMAP_SENDER_FILTERS=klarna,paypal,bestellung,order,invoice +``` + +In embedded connector mode, the API process receives FinTS PIN/TAN and IMAP +password inputs while the request is running. In separate local-agent mode, +those inputs stay out of the API process. In both modes, connector metadata and +normalized observations are what get stored; credentials are not written to the +database. + +## Scope + +FinTS account and transaction retrieval is implemented and can run embedded in +the API or in the separate local agent. It still depends on your bank supporting +FinTS PIN/TAN access and on you providing the bank-specific endpoint and login +data. IMAP folder listing, scanning, email parsing, preview, and import are +implemented for the PoC. PayPal CSV and email evidence are the supported PayPal +PoC path. PSD2 aggregator connectors are still scaffolded. + +## Tests + +```sh +pytest +npm run lint:web +npm run build:web +``` + +The Playwright MVP smoke test expects the API and web app to be running: + +```sh +npx playwright install +npm run test:e2e +```