# Finance System v0.2 Decisions

This reference captures durable design decisions from the user's Finance System planning session. Use it as the baseline before drafting v0.3 or implementing MVP work.

## Topic boundary

- Telegram topic: **Finance System – Architektur & Scripts**.
- Scope: technical architecture, imports, CSV processing, data models, dashboards, reports, automations, error analysis and optimization.
- Finance strategy questions should be routed to the separate finance strategy topic.

## User's target system

A rule-based finance management and decision-support system for stocks, ETFs, crypto and cash. It is not a trading bot.

Roles of the system:

1. Monitoring: what is happening?
2. Analysis: why is it happening?
3. Recommendation: what would be sensible?
4. Decision: what does the human choose?
5. Documentation: why was it chosen?

## Binding v0.2 decisions

- Base currency: **CHF**.
- Holdings in CHF, EUR and USD must store original currency values plus CHF equivalents via historical FX.
- Platforms/accounts to show separately and in aggregate:
  - Raiffeisenbank: cash positions/general overview.
  - PostFinance: individual stocks, ETFs and crypto overview.
  - True Wealth: ETF positions.
  - Crypto-Coins: separate coin positions.
- Existing Google Drive documents under `Finanzen/01 Aktueller Stand Portfolios` are real-world input test cases, not final data architecture.
- Existing portfolio files likely provide snapshots, not full transaction history. Treat as `initial_position_snapshot` / `initial_cash_snapshot` where needed.
- Crypto quantities from snapshots are relevant; stale crypto market values must not be used for current valuation. Recalculate via CoinGecko.
- Future ongoing data entry should be primarily through dashboard manual entry/search, not recurring arbitrary export formats.
- Direct broker/bank APIs are later-phase only.

## Required MVP 1 functions

- Capture transactions.
- Capture platform/account.
- Calculate active positions.
- Calculate cash.
- P&L per position and total.
- Total Return in CHF.
- Fees.
- Dividends/distributions.
- Swiss withholding tax 35% and foreign withholding tax separately.
- FX effects separately.
- Watchlist.
- Manual entry.
- CSV import/export.
- PDF/HTML/Markdown instant report.
- Platform views for Raiffeisen, PostFinance, True Wealth, Crypto-Coins.
- Gesamtportfolio view.

Not MVP 1:

- complex news analysis.
- analyst ratings.
- opportunity scanner.
- ML/LLM analysis.
- direct broker connections.
- automated order execution.

## Dashboard tech recommendation

MVP: **Streamlit + SQLite + SQLAlchemy/Pandas/Plotly**.

Reasoning:

- Fast and stable MVP development.
- Python-native ledger/accounting/reporting stack.
- Forms, tables, filters and charts are quick enough for MVP.
- Local/private deployment is straightforward.
- Business logic can later move behind FastAPI, with React/PWA or another UI.

Compared options:

- Dash/Plotly: strong analytics, more boilerplate.
- NiceGUI: modern workflows, smaller ecosystem for data dashboards.
- FastAPI + React: best long-term architecture, too heavy before ledger correctness is proven.

## Canonical table areas

- `platforms`
- `accounts`
- `instruments`
- `transactions`
- `cash_ledger`
- derived `positions_current`
- `dividends_distributions`
- `market_prices`
- `fx_rates`
- `watchlist_items`
- `alerts`
- `decision_journal`
- `reports`
- `data_quality_issues`

## Standard transaction CSV fields

Required header baseline:

```text
transaction_id_external,transaction_type,platform,account,trade_date,settlement_date,asset_class,name,ticker,isin,coingecko_id,quantity,price_original,gross_amount_original,fee_original,tax_original,net_amount_original,currency_original,fx_rate_to_chf,fx_source,notes
```

Optional:

```text
category,target_weight_pct,investment_case,exit_rule,decision_ref,source_file,source_row,quality_hint
```

## Transaction types

- buy
- partial_sell
- full_sell
- dividend
- etf_distribution
- fee
- tax
- cash_deposit
- cash_withdrawal
- fx_conversion
- crypto_buy
- crypto_sell
- crypto_transfer
- staking_reward_later
- initial_position_snapshot
- initial_cash_snapshot
- manual_correction

## Income/dividend fields

Always distinguish:

- gross amount.
- Swiss withholding tax 35%.
- foreign withholding tax.
- other tax.
- net amount.
- original currency.
- historic FX rate on payment date.
- CHF gross/net equivalents.
- account/platform.
- ISIN/ticker.
- payment date.
- ex-dividend date when available.

Plan Swiss tax view with year-end values, dividends/distributions, withholding summary and export for tax documents. Later incorporate ESTV/ICTax values.

## Market data providers

Design provider adapters and rate-limit protection for:

- Stocks/ETFs: Finnhub, Financial Modeling Prep, Twelve Data, Stooq, Alpha Vantage selectively, Yahoo Finance fallback only.
- Crypto: CoinGecko primary; later DefiLlama for DeFi/TVL.
- Swiss tax: ESTV/ICTax lists for year-end/tax values.

Rules:

- Cache responses.
- Store historical prices/FX locally.
- Batch where possible.
- Rate-limit queue per provider.
- Backoff on 429.
- Store provider and timestamp with every value.
- Warn on stale or conflicting data.
- Dashboard reads from DB; scheduled jobs update APIs.

## Initial score rules

Only MVP scores:

- Trend Score: simple price vs 50DMA/200DMA and recent performance.
- Portfolio Fit Score: actual vs target weight and target bands.
- Risk Score: concentration, drawdown/loss thresholds, volatility where available, data quality.

Prepare but do not treat as MVP core:

- Fundamental Score.
- Sentiment Score.
- Analyst Score.

## Alert priorities

Three labels: Info, Wichtig, Kritisch.

Examples:

- Info: watchlist zone reached, dividend recorded, report generated, market data older than 24h.
- Wichtig: position >20% over target, daily loss >5%, price below 200DMA, cash quote outside target band.
- Kritisch: portfolio drawdown >10%, single-position loss >20%, hard exit rule triggered, conflicting critical data source, missing FX for transaction.

## Security/Git rules

- GitHub only for code, scripts, schemas, tests, docs and synthetic examples.
- Never commit financial data, raw exports, reports with real numbers, DBs, PDFs, DOCX, XLSX, screenshots, API keys or credentials.
- Private GitHub is not a financial data vault.
- Use secret scanning and strict `.gitignore` before every commit.