# Finance System v0.4 Implementation Blueprint

Updated 2026-05-14.

v0.4 is the MVP 1 implementation blueprint, not another feature collection. It defines the technical build basis for SQLite + Python + Streamlit, still without code and without real financial data in Git.

## MVP 1 schema tables

Required SQLite tables:
- `platforms`, `accounts`, `instruments`
- `transactions`, `positions_snapshot`, `cash_balances`
- `fx_rates`, `market_prices`
- `crypto_wallets`, `crypto_assets`, `crypto_holdings`, `crypto_transactions`, `crypto_prices`
- `watchlist`, `reports`, `alerts`, `audit_log`, `import_sessions`, `decision_journal`

Conventions:
- IDs are TEXT UUIDs.
- Dates/timestamps are ISO strings.
- Monetary values and quantities are NUMERIC validated with Python Decimal logic.
- JSON fields are TEXT containing JSON.
- `positions_snapshot`, `cash_balances`, and `crypto_holdings` are derived/controlled state; ledgers remain source of truth for new movements.

## Ledger rules

- Initial snapshots are start balances only, not historical truth.
- New movements after system start are transaction-based.
- Buy increases quantity and cost basis; cash decreases.
- Sell decreases quantity, cash increases, realized P&L uses weighted-average cost in MVP.
- Dividends/distributions do not change quantity; net cash increases; gross/taxes stored for transparency.
- FX conversions move cash between currencies and store implied FX/fees.
- Crypto buy/sell/transfer use `crypto_transactions`; transfer is not buy/sell.
- Manual corrections require notes and audit entries.

## CHF/FX

- Base currency is CHF.
- Foreign currency transactions require original currency, original amount, historical FX to CHF, source, CHF equivalent, and FX status.
- Missing FX: `fx_status='missing'`, quality incomplete, critical alert if confirmed.
- Manual FX override allowed only with note/source and audit action `fx_override`.
- Stale/conflicting FX marked explicitly; no false precision in reports.

## Initial crypto wallets

Seed wallet/platform options:
- PostFinance Crypto
- Ledger
- MetaMask
- Kraken
- Binance
- Coinbase
- Sonstige Wallet
- Sonstige Exchange

Wallet addresses are optional and not required in MVP 1.

## Streamlit pages

- Command Center
- Gesamtportfolio
- Plattformansichten: Raiffeisen, PostFinance, True Wealth, Crypto
- Aktien/ETF-Portfolio
- Crypto-Seite
- Wallet-Übersicht
- Transactions/Ledger
- Watchlist
- Reports
- Alerts
- History/Audit
- Settings/Data Quality

## Crypto PDF template

Crypto PDF includes title, creation timestamp, CHF base currency, data timestamp, total crypto CHF, optional USD/EUR, coin overview, wallet overview, detail per coin by wallet, price source, last price update, last wallet verification, data quality warnings, notes, and disclaimer: holdings overview, not a full tax return.

## Final MVP CSV templates

- `accounts.csv`
- `instruments.csv`
- `transactions.csv`
- `crypto_wallets.csv`
- `crypto_holdings_initial.csv`
- `crypto_transactions.csv`
- `watchlist.csv`
- `cash_balances_initial.csv`

Use UTF-8, ISO dates, dot decimals, synthetic examples only in repo.

## Hard validation rules

- Buy quantity > 0.
- Sell cannot create negative balance unless confirmed correction.
- Crypto transfer requires source and target wallets and they must differ.
- Wallet name unique.
- CoinGecko ID strongly recommended; missing ID creates warning.
- Foreign currency transaction needs FX rate or explicit missing status.
- Confirmed transaction requires audit log entry.
- Manual correction requires note.
- Initial snapshot must be marked as such.
- Legacy crypto values must never be current valuation.
- Imports must be idempotent via external ID or row hash.

## Implementation phases

1. Project structure, DB, dummy data.
2. Ledger and position calculation.
3. Crypto inventory and wallets.
4. Streamlit dashboard core pages.
5. CSV import/export.
6. Market data and CoinGecko prices.
7. FX rates and CHF valuation.
8. Reports, especially Crypto PDF.
9. Audit log and data quality.
10. Tests and security review.

## Test concept

Only synthetic data in repo: dummy stocks, ETFs, crypto assets, wallets, FX rates and transactions. Test buy, sell, dividend, FX, crypto transfer, negative balance, missing price, missing FX, duplicate imports and audit requirement.

## Privacy/Git

Repo may contain code, docs, config examples and synthetic examples only. Never commit real financial data, DBs, reports, exports, backups, spreadsheets, PDFs, DOCX, real CSV/JSON, API keys, credentials, screenshots with values. Use `.gitignore`, secret scan and local/encrypted runtime storage.

## Telegram

Prepared but not MVP priority: parse later buy/sell/transfer messages into pending drafts, ask for missing fields, require explicit confirmation, then write ledger/crypto/audit entries. No silent final booking.