# TrueWealth-style portfolio advisor replacement

Use when the user wants Phase 8 / Portfolio Advisor work in the Finance System rather than the CryptoTradingBot topic.

## Routing

- Continue this work in Telegram topic **"Finance System - Architektur & Scripts"**.
- Finance Dashboard is the primary UI and decision cockpit.
- Crypto_Agent is only a read-only data source for crypto/trading risk and scorecards.
- The trading-bot topic should stay focused on automatic trading, paper evidence, and live-readiness gates.

## Product goal

Build a JARVIS Finance Dashboard module that can replace the TrueWealth robo-advisor by showing the whole household/personal portfolio, not only TrueWealth assets:

- Cash, bank accounts, TrueWealth ETFs, self-managed ETFs, single stocks, crypto, alternatives.
- Local dashboard may display exact amounts when the user has approved that scope.
- Chat summaries should avoid exposing exact amounts unless explicitly requested for the current scope.
- No automatic broker execution: recommendations are preview/audit only.

## TrueWealth UX/features to emulate and improve

Core screens:

- Portfolio cockpit with total assets, total return, strategy/risk KPIs, diversification, investment universe, currency hedging status.
- Asset-allocation donut with target-vs-current table.
- Clickable donut drilldown: total portfolio → asset class → subcategory/region/sector → effective positions.
- Detail tabs: holdings, transactions, companies/top holdings, instruments, currency risk, product type, liquidity, total costs, product costs.
- Performance area: performance, contribution, benchmarking, projected return, simulated history, risk.
- Benchmarking: portfolio vs multi-asset benchmark, target weights toggle, custom benchmarks, cost toggle, periods like 1M/YTD/1Y/5Y/Max/calendar.
- Risk: histogram/probability view with horizon slider, loss/gain probabilities, expected return, volatility and explanatory text.
- Reports: performance PDF, return-contribution PDF, rebalancing proposal, risk report.

JARVIS improvements over TrueWealth:

- Analyze total wealth across all depots/accounts, not only TrueWealth.
- Merge ETF lookthrough and single positions into effective sector/region/company exposure.
- Include crypto exposure and Crypto_Agent status as risk context, not trading authority.
- Add cash/budget context, custom target allocations, scenario stress tests, and audit history.

## Data model/engine components

Suggested domain objects:

- `PortfolioSource`, `PortfolioSnapshot`, `PortfolioPosition`.
- `InstrumentMaster`, `InstrumentClassification`, `EtfLookthrough`.
- `TargetAllocation`, `AllocationBand`, `DiversificationScore`.
- `RebalanceProposal`, `AdvisorRecommendation`, `ScenarioResult`, `AdvisorAuditLog`.

Advisor modules:

- snapshot builder, classification, allocation engine, diversification engine, rebalance engine, recommendation engine, scenario engine, TrueWealth import mapper, Crypto_Agent context adapter.

## Rebalancing rules

- Use current-vs-target drift with tolerance bands, not exact percentage chasing.
- Prefer new contributions to correct underweights before selling.
- Sell only for material drift, concentration risk, or strategy change.
- Include transaction costs, FX costs, spreads, taxes/stamp duty/fees as warnings or future inputs.
- Recommendations must carry reason, affected positions, expected effect, data quality, risk warning, and `execution_allowed=false` in v1.

## UI anti-overload pattern

Progressive disclosure:

1. Cockpit: one status, top recommendation, main reasons.
2. Cards: allocation, risk, diversification, data quality, rebalancing.
3. Donut/drilldown with breadcrumbs and filter chips.
4. Detail drawer for positions/instruments.
5. Tables only after the user drills down.

Common filters:

- All assets, TrueWealth, own ETFs, single stocks, crypto, cash.
- Depot/account/source.
- Currency, region, sector, asset class.
- Only deviations, only recommendations, only high risk.

## Safety/audit

- `auto_trade=false`, `auto_book=false`, `broker_execution=false`, `requires_user_confirmation=true`, `audit_required=true`.
- Workflow: analysis → proposal → preview → manual decision → audit status.
- Allowed actions in v1: details, mark reviewed, postpone, note, export report, prepare order proposal.
- Not allowed in v1: direct buy/sell/auto rebalance.