# Portfolio Advisor visual drilldown cockpit

Use this when extending the FinanceManager TrueWealth replacement / Portfolio Advisor UI.

## Boundary

- Keep full Portfolio Advisor functionality inside **FinanceManager**, not the general JARVIS overview portal.
- The JARVIS portal may link/handoff and show safe status, but must not become the advisor UI or expose exact financial values.
- FinanceManager may show exact local values according to the user's FinanceManager scope.

## Contract pattern

Extend the advisor snapshot with explicit view-model sections rather than embedding UI-only literals in Streamlit code:

- `AllocationSlice` for source and asset allocation.
- `DrilldownNode` for clickable/selectable drilldowns below donut segments.
- `LookthroughPlaceholder` for TrueWealth/ETF/single-stock exposure dimensions.
- `ImportSourceStatus` for TrueWealth screenshot/PDF mapping readiness.
- Workflow steps must stay preview-only by default (`execution_allowed=False`).

Recommended dimensions for lookthrough placeholders:

- Top Holdings
- Assetklasse
- Region / Land
- Sektor
- Währung
- Produkttyp
- TER/Kosten
- Liquidität

## UI pattern

For the Streamlit Portfolio page:

1. Preserve the existing user position table and detail panel.
2. Add a compact Portfolio Advisor cockpit near the top:
   - Source donut: TrueWealth / own ETFs-stocks / Cash / Crypto / Other.
   - Asset Allocation donut: equities, cash, crypto, commodities, real estate, bonds.
   - Segment selector as the reliable Streamlit-compatible "clickable drilldown" control.
   - Drilldown table for the selected segment.
3. Add tabs for:
   - Lookthrough
   - TrueWealth Import
   - Guardrails
4. Use Plotly `go.Pie(hole=0.58)` for a real donut, with a safe `st.bar_chart` fallback if Plotly import/rendering fails.
5. Mirror the same model into any admin/detail `Portfolio Übersicht` page, but do not duplicate business logic there.

## TrueWealth import staging

Represent the import plan before parser implementation:

- `*.png` screenshots → source allocation, asset allocation, drilldown nodes, risk scorecards.
- `True Wealth_performance.pdf` → performance, benchmarking, simulated history.
- `True Wealth Renditebeitrag nach Anlageklasse.pdf` → return contribution by asset class.

Rohdateien stay local/Drive and must not be committed to Git. Store only structured, reviewed mapping outputs.

## Verification checklist

- Unit test the advisor snapshot shape: exact local source values, drilldown nodes, lookthrough placeholders, import source statuses, and no workflow execution allowed.
- Run targeted tests for portfolio/cash/TrueWealth accounting plus CORS/API shape if touched.
- Run `ruff check`, `py_compile`, and a local Streamlit smoke.
- Browser-smoke the Portfolio page for visible text: `Portfolio Advisor / TrueWealth-Ersatz`, `Donut-Segment`, `Lookthrough`, `TrueWealth Import`, `Guardrails`.
- Before push, remove transient `uv.lock` if the repo intentionally does not track it.