# Finance System v0.4.1 Corrections

Updated 2026-05-14.

Accepted corrections layered on top of v0.4 before implementation planning.

## Ledger/Crypto coupling

`transactions` and `crypto_transactions` remain separated, but every crypto transaction with fiat/cash/CHF impact must be representable in the general ledger:

- Crypto buy with fiat amount: general `transactions` row for cash/FX/fee/CHF impact + `crypto_transactions` row for coin quantity/wallet details; link via `crypto_transactions.transaction_id` or booking group.
- Crypto sell with fiat amount: same coupling for fiat proceeds/cash impact and coin reduction.
- Pure wallet transfer: `crypto_transactions` only if no fiat movement.
- Crypto fee: coin fee reduces coin quantity; fiat fee creates general ledger fee; fee in another coin is a separate coin reduction with audit/quality handling.

Goal: total wealth, cash, FX, fees and performance must never drift apart.

## Truth model

Truth is:
1. confirmed transactions;
2. confirmed initial snapshots.

`positions_snapshot`, `cash_balances`, and `crypto_holdings` are calculated states, caches or control views — not primary truth.

Holdings must not be changed by direct overwrites except through:
- transaction;
- initial snapshot;
- `manual_adjustment` with note and audit log.

## Cash logic

`cash_balances` is for initial balances and control snapshots. After system start, cash is calculated primarily from ledger transactions.

- `initial_cash_snapshot` = start truth.
- Afterwards: cash deposits/withdrawals, buys/sells, dividends, fees, taxes and FX conversions drive cash.
- Manual cash correction requires note, audit log, and data-quality marker if it creates discrepancy.

## Cost basis

MVP 1 uses Weighted Average Cost for internal performance.

- No full tax-lot accounting in MVP 1.
- FIFO/LIFO/specific tax lots are optional later.
- Reports must not imply tax-return correctness.

## Runtime outside repo

Production runtime data defaults outside the Git repository, e.g. `~/jarvis_runtime/finance-system/`.

Git may contain only code, docs, synthetic test data and example configs. Never commit real SQLite DBs, CSVs, reports, exports, portfolio statements, API keys, secrets, OAuth files or screenshots with financial values.

## Stack

MVP 1 stack confirmed: Streamlit + SQLite + Python. Later option: FastAPI + React if mobile UX, multi-user, auth, or professional operations become more important.