# Dashboard User/Admin UX + Runtime Review Pattern

Use when the user asks to make the Finance dashboard more usable for normal operation after crypto/broker/import foundations are in place.

## User/Admin navigation pattern

- Split Streamlit navigation into two explicit modes:
  - **User Mode / Alltag**: Command Center, Portfolio, Crypto, Wallets, Equities/ETFs, Watchlist, Reports.
  - **Admin / Review / Debug**: Ledger, Audit, Alerts, Data Quality, Import Wizard, Settings, Crypto Manage, Equity/ETF Manage, Manual Review Queue.
- User Mode must feel like a professional investment/portfolio dashboard, not a developer/admin surface: clear summary first, then charts/cards, then concise position lists, then selectable details/actions.
- Preferred interaction flow: **Überblick → Position auswählen/öffnen → Details → Aktion**. If Streamlit row-click is unreliable, use selectboxes or card/button patterns; do not leave actions as static text only.
- In User Mode, hide technical identifiers and raw review fields by default: `asset_id`, `wallet_id`, `instrument_id`, `entity_id`, `rule_id`, `source_id`, `dedup_key`, raw provider payloads, candidate counts, `provider_symbol_status`, `hedge_status`, raw `quality_status`, and provider mapping internals.
- Keep those fields available in Admin/Review views; never delete auditability to make the dashboard pretty.
- Translate technical statuses into readable German labels/badges (`missing_market_price` → `Preis fehlt`, `missing_fx` → `FX-Kurs fehlt`, `cost_basis_uncertain` → `Einstand unvollständig`, `fresh` → `Aktuell`, `stale` → `Veraltet`, `unknown` → `Ungeklärt`, `mapped` → `Bestätigt/Zugeordnet`).
- User Mode tables should default to at most 7–8 visible columns, no IDs, no raw data, no long ISO/debug timestamps; format values as `CHF 12’345.67`, `12.3 %`, readable dates, and Decimal quantities without scientific notation.
- Page render functions must remain local-read only: no CoinGecko/market-provider calls during dashboard reload.

## Command Center / Portfolio UX

- Command Center is a daily overview, not a raw status console. Show only 4–6 top cards first: total portfolio CHF, Crypto CHF, Aktien/ETF CHF, Cash CHF, critical points, last price update.
- Below the cards, keep at most three user sections: **Was ist wichtig?** (top 3–5 readable warnings, no IDs), **Top Positionen**, and **Schnellaktionen**. Move technical tables into an expander labelled like `Technische Details anzeigen`.
- Portfolio overview should show asset-class allocation and platform values with simple charts before any tables. Keep User Mode position tables concise; provider/hedge/debug fields belong in Admin/Data Quality only.

## Crypto UX read models

- Build aggregated coin-level rows across wallets: coin, symbol, total quantity, cached CHF price, cached CHF value, portfolio share, wallet count, price status, last local price update, and user actions.
- Crypto page should begin with summary cards: Crypto total CHF, coin count, wallet count, coins without price, largest position, and last price update.
- Add simple visual orientation: allocation by coin, allocation by wallet, and top coins by CHF value (bar/donut; keep it simple).
- Add wallet drilldowns per coin: wallet name/type, quantity, cached CHF value, share of coin, last verification, note/actions.
- Coin detail should open from a selection/card/button and show coin name/symbol, total quantity/value, cached price, portfolio share, price status, last price update, wallet split, and actions (add, correct, transfer, set to zero, audit/history).
- Add wallet overview cards: total cached value, wallet count, missing-verification count, largest wallet, and a `Neues Wallet` entry. Per-wallet detail should show coins, cached valuation, last verification, notes and actions.
- Format missing prices as `nicht bewertet`; do not silently treat missing/stale prices as zero-value certainty.
- Preserve Decimal/Text formatting and avoid scientific notation in UI-facing quantities.

## Crypto Manage UX actions

- Prefer action cards over raw forms/tables:
  - Coin hinzufügen
  - Bestand korrigieren
  - Transfer zwischen Wallets
  - Bestand entfernen / auf 0 setzen
  - Neues Wallet
  - Verlauf / Audit
- Do not show all forms at once. Show the matching form only after an action is selected.
- Structure forms as a wizard-like flow: **1 Was? → 2 Wo? → 3 Menge/Datum → 4 Review → 5 Bestätigen**. Keep review/confirmation explicit.
- Add/correct/remove must use domain helpers that create audited transactions or `manual_adjustment` records. Never mutate `crypto_holdings` directly from the dashboard.
- Removing a coin means an audited adjustment to zero, not deletion.
- Transfers require source wallet, target wallet, same asset, positive Decimal quantity, and audit log.
- New wallet creation should allow optional provider/chain/notes; wallet address must not be mandatory.
- Use explicit confirmation checkboxes and mandatory notes for manual adjustments/removals or incomplete history.

## Alerts UX

- In User Mode, show alerts as readable cards, not a technical event table: severity counts (`Kritisch`, `Wichtig`, `Info`), title, explanation, affected object, and actions (`Prüfen`, `Ignorieren`, `Details`).
- Hide `rule_id`, `entity_id`, dedup keys, fingerprints and raw messages in User Mode; keep them in Admin/Review.
- Phrase alerts in user-facing German, e.g. `FX-Kurs fehlt für VTI` with a short consequence-oriented description.

## Equity/ETF normal-view demotion pattern

- ISIN remains primary identity; ticker/exchange/provider symbol are market-data mappings.
- If the user has manually confirmed mappings, mark them with a user-confirmed/audited status in runtime DB and resolve/demote active mapping alerts from the normal dashboard view.
- Do not erase technical placeholder rows or review history; keep unresolved details visible in Admin/Data Quality.
- Report only aggregate counts of confirmed mappings/alerts/audit rows; do not echo portfolio values or row-level financial data.

## Runtime DB safety when changing metadata

- Before runtime metadata changes, create a runtime backup outside Git and verify the DB exists.
- Apply migrations before inspection/update.
- Write audit events for user-confirmed mapping/status changes.
- After update, verify aggregate counts and active alert state only.

## Test pattern

Add unit tests for:

- User-mode read models hiding technical IDs while admin mode can expose them.
- User Mode Crypto/Portfolio tables not exposing IDs/raw provider/debug fields and staying concise.
- Crypto summary cards and coin aggregation across multiple wallets.
- Chart datasets for coin allocation, wallet allocation, asset classes and platform values.
- Coin detail opening via selection/card/button and showing wallet split plus actions.
- Wallet detail showing coins in that wallet plus actions.
- Alert cards rendering readable titles/descriptions instead of raw rule IDs.
- Crypto Manage showing action cards first and not rendering all forms before action selection.
- Wallet drilldown/overview formatting and cached valuation.
- Manage helper transfer/audit behavior.
- Dashboard smoke renders with fake Streamlit and no live API path.

## Streamlit limits / fallback UX

- Streamlit is acceptable for MVP: `st.metric`, `st.bar_chart`, `st.expander`, `st.selectbox`, button grids, and session-state-based detail panels.
- True row-click and per-row buttons in native dataframes are limited; prefer selectboxes or cards with `Öffnen` buttons when needed.
- If UX becomes route-heavy or component-rich, document the limitation and keep MVP safe; later FastAPI + React would handle clickable tables/cards, route-based details, responsive design and workflow state machines better.

## Pitfalls

- Do not turn the normal dashboard into an admin/raw-table dump; the user explicitly wants an Alltag view.
- Do not sacrifice auditability for UX: technical fields move to Admin, not out of the system.
- Running tests before Git-safety creates `__pycache__` and `.pytest_cache`; clean them before the safety scan.