vault-dash/docs/ROADMAP.md

# Vault Dashboard Roadmap

## Overview
A prioritized roadmap for the Vault Dashboard Lombard loan hedging platform.

## Legend
- **Priority**: P0 (Critical), P1 (High), P2 (Medium), P3 (Low)
- **Dependencies**: Features tagged with `[depends: ID]` require the named feature to be completed first
- **Effort**: S (Small), M (Medium), L (Large)

---

## Phase 1: Data Foundation (Foundation Layer)

### DATA-001: Live Price Feed Integration [P0, M] **[foundation]**
**As a** portfolio manager, **I want** real-time gold price updates **so that** my LTV calculations reflect current market conditions.

**Acceptance Criteria:**
- Integrate yfinance/live data for GLD spot price
- Update prices every 30 seconds via WebSocket
- Display last update timestamp
- Fallback to cached data if feed fails

**Technical Notes:**
- Create `app/services/price_feed.py` with async price fetching
- Extend existing WebSocket manager in `app/services/websocket.py`
- Store prices in Redis with 60s TTL

**Dependencies:** None

---

### DATA-002: Options Chain Data [P0, L] **[depends: DATA-001]**
**As a** trader, **I want** live options chain data for GLD **so that** I can evaluate protective put strikes and premiums.

**Acceptance Criteria:**
- Fetch options chains from yfinance or IBKR API
- Display strikes, expiration dates, bid/ask, implied volatility
- Cache chain data for 5 minutes
- Support filtering by expiration (30/60/90 days)

**Technical Notes:**
- Create `app/services/options_chain.py`
- Add `/api/options/chain` endpoint
- Update Options Chain page (`app/pages/options.py`)

**Dependencies:** DATA-001

---

### DATA-003: Greeks Calculation [P1, M] **[depends: DATA-002]**
**As a** risk manager, **I want** real-time Greeks calculations **so that** I understand my hedge sensitivity.

**Acceptance Criteria:**
- Calculate Delta, Gamma, Theta, Vega for selected options
- Display Greeks in options chain view
- Show portfolio-level Greeks if positions held
- Use Black-Scholes model with live IV

**Technical Notes:**
- Create `app/services/pricing.py` with B-S model
- Add QuantLib integration (optional dependency)
- Cache calculations for performance

**Dependencies:** DATA-002

---

## Phase 2: Portfolio & Risk (Core Features)

### PORT-001: Portfolio State Management [P0, M] **[depends: DATA-001]**
**As a** user, **I want** to configure my actual portfolio (gold value, loan amount) **so that** LTV calculations match my real position.

**Acceptance Criteria:**
- Settings page with editable portfolio parameters
- Store config in Redis/database
- Validate LTV < 100%
- Show current vs recommended collateral

**Technical Notes:**
- Extend `app/pages/settings.py`
- Create `app/models/portfolio.py` with Pydantic models
- Add persistence layer (Redis JSON or SQLite)

**Dependencies:** DATA-001

---

### PORT-002: Alert Notifications [P1, M] **[depends: PORT-001]**
**As a** risk manager, **I want** alerts when LTV approaches margin call thresholds **so that** I can take action before liquidation.

**Acceptance Criteria:**
- Configurable alert thresholds (default: 70%, 75%)
- Browser push notifications
- Email notifications (optional)
- Alert history log

**Technical Notes:**
- Create `app/services/alerts.py`
- Integrate browser notifications API
- Add `/api/alerts/configure` endpoint
- Background task to check thresholds

**Dependencies:** PORT-001

---

### PORT-003: Historical LTV Chart [P2, M] **[depends: PORT-001]**
**As a** user, **I want** to see my LTV history over time **so that** I can identify trends and stress periods.

**Acceptance Criteria:**
- Store LTV snapshots every hour
- Display 7/30/90 day charts
- Show margin call threshold line
- Export data as CSV

**Technical Notes:**
- Create `app/services/history.py`
- Use TimescaleDB or Redis TimeSeries (optional)
- Integrate with existing chart components

**Dependencies:** PORT-001

### PORT-004: Hashed Workspace Persistence [P0, L] **[depends: PORT-001]**
**As a** user, **I want** my dashboard settings and scenarios to live inside a shareable hashed workspace URL **so that** I can return on a new device or share the exact workspace with someone else.

**Acceptance Criteria:**
- First visit with no known workspace shows a welcome/bootstrap page at `/`
- Welcome page contains a short description and a clear call to action such as `Get started`
- Clicking `Get started` creates a new workspace id (UUID/hash-like token), stores it in a browser cookie, and redirects to `/{workspace_id}`
- Returning visitors with a valid workspace cookie who visit `/` are redirected to their existing workspace
- Visiting an existing `/{workspace_id}` loads that workspace without requiring the cookie
- Workspace URL is copyable/shareable and restores the same settings on another device/browser
- Settings persistence is scoped by workspace id rather than one global local file
- Existing pages (`/{workspace_id}`, `/{workspace_id}/settings`, `/{workspace_id}/overview`, `/{workspace_id}/hedge`, `/{workspace_id}/backtests`, `/{workspace_id}/event-comparison`) read/write the active workspace state
- Invalid or unknown workspace ids show a clear recovery path instead of a server error
- Browser test verifies:
  - first visit shows the welcome page
  - clicking `Get started` creates/redirects to a workspace route
  - cookie-backed revisit to `/` returns to the same workspace
  - visiting the same workspace URL in a fresh context restores the same settings

**Technical Notes:**
- Introduce a workspace model/repository keyed by generated id
- Prefer server-side persistence keyed by workspace id; cookie stores only the id, not the full state
- Keep workspace ids opaque and non-sequential
- Treat `/` as a dedicated bootstrap/welcome route rather than making every page handle bootstrap behavior
- Workspace pages can remain focused on workspace-aware rendering only; bootstrap logic stays isolated at `/`
- Ensure routing design stays compatible with existing NiceGUI pages before implementation

**Dependencies:** PORT-001

---

## Phase 3: Strategy Execution (Advanced Features)

### EXEC-001: Strategy Builder [P1, L] **[depends: DATA-003]**
**As a** trader, **I want** to build and compare hedging strategies **so that** I can choose optimal protection.

**Acceptance Criteria:**
- Select strategy type (protective put, collar, laddered)
- Choose strikes and expirations
- See P&L payoff diagrams
- Compare cost vs protection level

**Technical Notes:**
- Extend `app/pages/hedge.py`
- Create `app/services/strategy_builder.py`
- Add payoff chart visualization
- Store strategy templates

**Dependencies:** DATA-003

---

### EXEC-002: IBKR Order Integration [P2, L] **[depends: EXEC-001]**
**As a** authorized user, **I want** to execute hedge trades directly from the dashboard **so that** I can act quickly on recommendations.

**Acceptance Criteria:**
- IBKR API connection (paper trading first)
- Preview order with estimated fill
- One-click execution
- Order tracking and status updates

**Technical Notes:**
- Create `app/services/broker.py` with IBKR API
- Add paper/live mode toggle
- Store credentials securely
- Order audit log

**Dependencies:** EXEC-001

---

### EXEC-003: Position Monitoring [P2, M] **[depends: EXEC-002]**
**As a** portfolio manager, **I want** to see my open hedge positions **so that** I know my current protection status.

**Acceptance Criteria:**
- Display open options positions
- Show expiration countdown
- Calculate net Greeks exposure
- Alert on approaching expiration

**Technical Notes:**
- Create positions table/view
- Sync with IBKR positions
- Update portfolio Greeks calculation

**Dependencies:** EXEC-002

---

## Phase 4: Reporting & Analytics (Polish)

### RPT-001: Strategy Report Generation [P3, M] **[depends: EXEC-001]**
**As a** compliance officer, **I want** PDF reports of hedging decisions **so that** I can document risk management.

**Acceptance Criteria:**
- Generate PDF with strategy rationale
- Include P&L scenarios
- Date range selection
- Export to email/share

**Technical Notes:**
- Use reportlab or weasyprint
- Create `app/services/reporting.py`
- Add download endpoint

**Dependencies:** EXEC-001

---

### RPT-002: What-If Analysis [P3, L] **[depends: DATA-003]**
**As a** risk manager, **I want** to simulate gold price drops **so that** I can stress test my protection.

**Acceptance Criteria:**
- Slider to adjust gold price scenarios (-10%, -20%, etc.)
- Show portfolio P&L impact
- Display hedge payoff under scenarios
- Compare protected vs unprotected

**Technical Notes:**
- Extend strategy builder with scenario mode
- Add sensitivity analysis
- Interactive chart updates

**Dependencies:** DATA-003

---

## Dependency Graph

```
DATA-001 (Price Feed)
├── DATA-002 (Options Chain)
│   ├── DATA-003 (Greeks)
│   │   ├── EXEC-001 (Strategy Builder)
│   │   │   ├── EXEC-002 (IBKR Orders)
│   │   │   │   └── EXEC-003 (Position Monitoring)
│   │   │   └── RPT-001 (Reports)
│   │   └── RPT-002 (What-If)
│   └── PORT-001 (Portfolio Config)
│       ├── PORT-002 (Alerts)
│       └── PORT-003 (History)
```

---

## Fast Follow-up Backlog

### DATA-002A: Lazy Options Loading [P0, S] **[depends: DATA-002]**
**As a** trader, **I want** the options page to render immediately **so that** it feels responsive and usable.

**Acceptance Criteria:**
- Initial page load fetches only expirations plus one default expiry chain
- Changing expiry fetches that expiry on demand
- Browser test verifies `/options` becomes visible quickly
- No visible 500/runtime error during page load

**Dependencies:** DATA-002

### DATA-001A: Live Overview Price Wiring [P0, S] **[depends: DATA-001, PORT-001]**
**As a** portfolio manager, **I want** the overview cards to use live quote data **so that** the displayed spot/LTV values are trustworthy.

**Acceptance Criteria:**
- Overview page uses live quote from service instead of hardcoded `215.0`
- Display source and last updated timestamp
- Margin call / LTV calculations use configured portfolio values
- Browser test verifies overview renders with live data metadata

**Dependencies:** DATA-001, PORT-001

### OPS-001: Caddy Route for Production Dashboard [P1, S] **[depends: deploy-stable]**
**As a** VPN user, **I want** to reach the deployed dashboard at `vd1.uncloud.vpn` **so that** I can access it without SSH port forwarding.

**Acceptance Criteria:**
- Caddy route proxies `vd1.uncloud.vpn` to local deployment container
- Route works over the VPN only
- Health check succeeds through Caddy
- Deployment docs include the route and where it lives

**Dependencies:** stable deployed app on VPS

### PORT-001A: Collateral Entry Basis in Settings [P1, M] **[depends: PORT-001]**
**As a** portfolio manager, **I want** to store my collateral entry basis **so that** the dashboard can derive position size consistently from either cost basis or weight. 

**Acceptance Criteria:**
- Settings supports entering either:
  - total collateral start value **and** entry price, or
  - gold weight directly
- Updating one mode calculates the other representation automatically
- Persist both the chosen input mode and the derived values needed by the app
- Validation prevents impossible or contradictory values (zero/negative price, value, or weight)
- UI makes the relationship explicit: `weight = start_value / entry_price`
- Browser-visible test covers switching modes and saving derived values

**Technical Notes:**
- Extend `PortfolioConfig` / settings persistence with entry-basis fields
- Keep overview and other consumers compatible with existing portfolio settings
- Prefer a single canonical stored representation plus derived display fields to avoid drift

**Dependencies:** PORT-001

### EXEC-001A: Named Strategy Templates [P1, M] **[depends: DATA-003]**
**As a** risk manager, **I want** protection strategies to be first-class named templates **so that** I can compare, reuse, and later edit hedge definitions.

**Acceptance Criteria:**
- Persist strategy templates with a stable id and display name
- Support at least initial system-defined templates (future user-editable names)
- Store template parameters separately from backtest scenarios
- Strategy templates are reusable by both live recommendation flows and backtests

**Technical Notes:**
- Add strategy template model/repository
- Separate template definition from strategy execution state
- Keep room for future user-editable naming and rule parameters

**Dependencies:** DATA-003

### BT-001: Synthetic Historical Backtesting [P1, L] **[depends: EXEC-001A, PORT-001]**
**As a** portfolio manager, **I want** to backtest hedge strategies against historical selloffs **so that** I can see which approach would have survived without a margin call.

**Acceptance Criteria:**
- Define a backtest scenario with start date, end date, collateral basis, and initial LTV
- Simulate at least one named hedge strategy over historical GLD prices
- Report max LTV, final equity, hedge cost, and whether a margin call would have occurred
- Compare protected vs unprotected outcomes for the same scenario
- Support known event replay such as the 2026 gold selloff window

**Technical Notes:**
- Start with synthetic/model-priced historical options rather than requiring point-in-time full historical chains
- Use historical underlying prices plus Black-Scholes/volatility assumptions
- Output both time series and summary metrics

**Dependencies:** EXEC-001A, PORT-001

### BT-002: Historical Daily Options Snapshot Provider [P2, L] **[depends: BT-001]**
**As a** quant user, **I want** real historical daily options snapshots **so that** backtests use observed premiums instead of only modeled prices.

**Acceptance Criteria:**
- Historical data provider abstraction supports point-in-time daily option chain snapshots
- Backtest engine can swap synthetic pricing for provider-backed historical daily premiums
- Contract selection avoids lookahead bias
- Provider choice and data quality limits are documented clearly

**Technical Notes:**
- Add provider interface for underlying history and option snapshot history
- Prefer daily snapshots first; intraday/tick fidelity is a later upgrade
- Candidate providers: Databento, Massive/Polygon, ThetaData, EODHD

**Dependencies:** BT-001

### BT-003: Selloff Event Comparison Report [P2, M] **[depends: BT-001]**
**As a** portfolio manager, **I want** event-based backtest reports **so that** I can answer questions like “which strategy got me through the Jan 2026 selloff?”

**Acceptance Criteria:**
- Event presets can define named historical windows
- Report ranks strategies by survival, max LTV, cost, and final equity
- Report highlights breach date if a strategy fails
- UI can show the unhedged path beside hedged paths

**Dependencies:** BT-001

### BT-001A: Backtest Scenario Runner UI [P1, M] **[depends: BT-001, EXEC-001A, PORT-001]**
**As a** portfolio manager, **I want** a thin backtest page where I can run a synthetic scenario and inspect the result **so that** the BT-001 engine is available through the product UI instead of only tests/services.

**Acceptance Criteria:**
- Add a backtest page with a simple scenario form for:
  - symbol
  - start date
  - end date
  - template selection
  - underlying units
  - entry spot
  - loan amount
  - margin call LTV
- Running the form executes the existing BT-001 synthetic backtest service
- Results show at least:
  - start value
  - end unhedged value
  - end hedged net value
  - total hedge cost
  - max LTV unhedged / hedged
  - margin-call outcome
- Results include a visible daily path chart/table comparing unhedged vs hedged values
- Invalid scenarios surface user-visible validation errors instead of server errors
- Browser test verifies the page can run one deterministic scenario end-to-end

**Technical Notes:**
- Keep this slice read-only and in-process; no run persistence required yet
- Reuse existing BT-001 models/services rather than adding a second execution path
- Prefer a single page that renders metrics first and a compact path visualization second
- Do not block on historical option snapshot providers; synthetic pricing is sufficient for the first UI slice

**Dependencies:** BT-001, EXEC-001A, PORT-001

### BT-003A: Event Comparison UI Read Path [P1, M] **[depends: BT-003, BT-001A]**
**As a** portfolio manager, **I want** to select a named selloff event and compare template outcomes in the UI **so that** event-comparison results are visible without invoking services manually.

**Acceptance Criteria:**
- Add an event comparison page or section that lets the user select:
  - event preset
  - one or more strategy templates
  - initial portfolio inputs
- Running the comparison executes the existing BT-003 comparison service
- UI displays ranked strategy results with at least:
  - rank
  - template name
  - survived margin call
  - max hedged LTV
  - hedge cost
  - final equity
- UI shows the selected event window metadata and the scenario dates actually used
- UI shows at least one simple visual comparison of hedged vs unhedged path behavior
- Empty template selection and invalid inputs surface user-visible validation states
- Browser test verifies one seeded event preset comparison renders ranked results

**Technical Notes:**
- Start with existing seeded event presets from `config/event_presets.json`
- Keep this slice read-only; no saved reports/downloads required yet
- Reuse `EventComparisonService` and avoid duplicating ranking logic in the UI layer
- Keep the output intentionally thin: ranked table first, deeper charts/details later

**Dependencies:** BT-003, BT-001A

### BT-001B: Backtest Defaults from Saved Portfolio [P1, S] **[depends: BT-001A, PORT-001A]**
**As a** portfolio manager, **I want** the backtest forms to prefill from my saved portfolio settings **so that** I do not have to re-enter start value, start price, weight, and loan inputs across pages.

**Acceptance Criteria:**
- `/backtests` defaults derive from the canonical saved portfolio/settings state
- `/event-comparison` defaults derive from the same canonical saved portfolio/settings state
- UI makes the implied starting position explicit (start value, start price, weight)
- Changes in settings are reflected in both backtest pages on reload
- Browser test verifies saved settings influence backtest defaults

**Technical Notes:**
- Reuse the existing portfolio/settings persistence path
- Avoid duplicating position-derivation logic between settings and backtest pages
- Keep BT-001A/BT-003A read-only with respect to persistence; settings remains the source of truth

**Dependencies:** BT-001A, PORT-001A

### BT-003B: Event Comparison Drilldown [P1, M] **[depends: BT-003A]**
**As a** portfolio manager, **I want** to inspect why one ranked strategy beat another **so that** the comparison page explains survival, cost, and path behavior instead of only showing a summary table.

**Acceptance Criteria:**
- Selecting a ranked strategy shows its daily path details
- UI exposes at least:
  - margin call days hedged/unhedged
  - total option payoff realized
  - total hedge cost
  - final equity
- UI highlights the worst LTV point and any breach dates
- User can compare the selected strategy path against the unhedged baseline and one other ranked strategy
- Browser test verifies drilldown content updates when selecting a ranked result

**Technical Notes:**
- Reuse existing `daily_path` and summary metrics from BT-001/BT-003 results
- Keep this slice read-only; no saved reports required yet
- Prefer progressive disclosure below the ranked table rather than a separate workflow

**Dependencies:** BT-003A

### BT-001C: Shared Historical Fixture/Test Provider Cleanup [P2, S] **[depends: BT-001A, BT-003A]**
**As a** developer, **I want** one shared deterministic historical fixture provider for backtest UI paths **so that** seeded browser tests and demo scenarios stay consistent and do not duplicate historical-window logic.

**Acceptance Criteria:**
- Deterministic historical fixture/provider logic is centralized instead of duplicated across page-specific services
- Supported seeded windows are explicit and fail closed outside allowed ranges
- Both `/backtests` and `/event-comparison` use the shared deterministic provider in browser-tested demo paths
- Tests cover the supported-window contract and failure mode

**Technical Notes:**
- Prefer a small shared test/demo provider abstraction over page-local fixture classes
- Keep live providers separate from deterministic seeded UI/demo behavior

**Dependencies:** BT-001A, BT-003A

## Implementation Priority Queue

1. **PORT-004** - Introduce hashed workspace persistence as the new state foundation
2. **BT-001B** - Prefill backtest UIs from canonical saved portfolio settings
3. **BT-003B** - Add event-comparison drilldown and explanation of ranking outcomes
4. **PORT-003** - Historical LTV visibility and export groundwork
5. **BT-002** - Upgrade backtests to real daily options snapshots
6. **BT-001C** - Consolidate deterministic historical fixture/demo provider logic
7. **EXEC-001** - Core user workflow
8. **EXEC-002** - Execution capability
9. Remaining features