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 user, I want to reach the deployed dashboard at lombard.uncloud.tech so that I can access it directly over HTTPS.

Acceptance Criteria:

• Caddy route proxies lombard.uncloud.tech to the deployment container
• HTTPS works with a valid certificate
• Health check succeeds through Caddy
• Deployment docs include the route and note that vd1.uncloud.vpn was retired

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

CORE-001: Explicit Unit/Value Classes for Domain Quantities [P1, L] [foundation]

As a developer, I want money, weight, spot-price, and quantity values to use explicit unit-aware value classes so that incompatible units cannot be mixed silently in calculations.

Acceptance Criteria:

• Introduce explicit domain value types for at least:
  • currency amount
  • currency per weight
  • gold/underlying quantity
  • weight unit
  • base currency
• All unit-bearing numeric values use decimal-based representation suitable for bookkeeping/accounting accuracy rather than binary floating point
• Each value object carries both numeric value and declared unit/currency metadata
• Implicit arithmetic between incompatible types is rejected by default
• Only explicit conversions and explicitly defined operators are allowed
• Conversions between supported weight units are implemented and tested
• Domain operations express intent clearly, e.g. multiplying Gold by CurrencyPerWeight yields Currency
• Existing high-risk calculation paths (overview, hedge, backtests, event comparison) are migrated away from raw float mixing for unit-bearing values
• Tests cover both valid conversions/operations and invalid combinations that must fail loudly

Technical Notes:

• Prefer small immutable value objects / dataclasses over loose primitives
• Use Python Decimal (or an equivalent decimal fixed-precision type) as the canonical numeric representation for money, quantities, and conversion-bearing domain values
• Add enums or equivalent typed constants for currency (USD, EUR, CHF, ...) and weight (grams, kilograms, oz)
• Make conversion APIs explicit, e.g. to_weight(...), to_currency(...), or named constructors
• Default operators should be conservative: fail closed unless a unit-safe operation is explicitly defined
• Start with gold/collateral and spot-price paths first, then extend to options/backtesting quantities where needed
• Define clear boundaries for interoperability with existing float-heavy libraries/services so conversion into/out of Decimal happens intentionally at the edges
• Use this story to remove the class of bugs caused by mixing physical-gold ounces, ETF-like units, USD notionals, and USD-per-weight spot quotes

Dependencies: None

CORE-001A: Decimal Unit Value Object Foundation [P1, M] [depends: CORE-001]

As a developer, I want a small core set of immutable Decimal-based value objects and enums so that unit-aware domain modeling exists before we migrate calculation paths.

Acceptance Criteria:

• Introduce foundational domain types for at least:
  • BaseCurrency
  • WeightUnit
  • Money
  • PricePerWeight
  • GoldQuantity / equivalent weight-bearing quantity type
• Core numeric fields use Decimal as the canonical representation
• Constructors/validators reject invalid or missing unit metadata
• Weight conversion methods are explicit and tested
• Unsupported arithmetic fails closed unless an operator is deliberately defined
• Tests cover constructors, conversions, equality/normalization expectations, and invalid operations

Technical Notes:

• Prefer a dedicated domain module such as app/domain/units.py or similar
• Keep the first slice focused on primitives and unit algebra, not page migration yet
• Add string/serialization helpers carefully so persistence remains deterministic
• See docs/CORE-001A_DECIMAL_UNITS_ARCHITECTURE.md for the implementation-ready design

Dependencies: CORE-001

CORE-001B: Overview and Hedge Migration to Unit-Safe Types [P1, M] [depends: CORE-001A, PORT-001A]

As a developer, I want overview and hedge calculations to use the new unit-safe Decimal value objects so that the most user-visible collateral math stops depending on raw float conventions.

Acceptance Criteria:

• Overview calculations use unit-safe types for collateral quantity, spot price, notional values, and margin-call math
• Hedge scenario calculations use unit-safe types for starting position, option contribution framing, and equity outputs where applicable
• The incompatible live-quote fallback path remains correct under the new model
• Existing visible outputs remain browser-verified on /overview and /hedge
• Regression tests cover previously discovered unit-confusion bugs

Technical Notes:

• Start with calculation helpers and view-model boundaries before touching every page widget
• Convert to/from legacy float-heavy libraries only at the edges, with explicit naming
• Preserve current Lombard/domain compatibility while migrating internals

Dependencies: CORE-001A, PORT-001A

CORE-001C: Backtests and Event Comparison Migration to Unit-Safe Types [P1, M] [depends: CORE-001A, BT-001, BT-003A]

As a developer, I want historical scenario inputs and outputs to use the new unit-safe Decimal value objects so that backtests stop mixing live portfolio units, historical units, and notional values implicitly.

Acceptance Criteria:

• Backtest scenario portfolio inputs are expressed via unit-safe Decimal types at the domain boundary
• Event-comparison scenario materialization uses explicit conversions from workspace value basis to historical units
• Historical entry spot, underlying units, and resulting notionals are no longer mixed as raw floats in core scenario setup paths
• Deterministic test/demo paths still work and remain browser-tested
• Tests cover both correct conversions and fail-closed invalid unit combinations

Technical Notes:

• Focus first on scenario/materialization boundaries and summary calculations rather than every chart payload
• Preserve deterministic fixture behavior while tightening the domain model
• This slice should make the current gold_value -> historical underlying_units conversion explicit in the type system

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

CORE-001D: External Boundary and Persistence Cleanup for Decimal Unit Types [P2, M] [depends: CORE-001B, CORE-001C]

As a developer, I want persistence and service boundaries to handle Decimal unit-safe types explicitly so that the new model remains reliable across JSON, APIs, caches, and third-party integrations.

Acceptance Criteria:

• Persistence format for unit-safe values is explicit and stable
• JSON/API serialization for Decimal-bearing unit objects is documented and tested
• Float-heavy provider integrations have named conversion boundaries
• Remaining raw-float domain hotspots are identified or removed
• Developer docs note when to use unit-safe value objects vs primitive edge values

Technical Notes:

• Keep transport/persistence schemas boring and explicit; avoid magic implicit coercion
• Consider typed DTOs at the edges if needed to keep core domain objects strict
• This is the cleanup slice that reduces backsliding after the initial migrations

Dependencies: CORE-001B, CORE-001C

Implementation Priority Queue

1. CORE-001A - Introduce Decimal-based unit/value object foundations before more calculation drift accumulates
2. CORE-001B - Migrate overview and hedge to unit-safe types on the most user-visible paths
3. PORT-004 - Continue hashed workspace persistence as the new state foundation
4. BT-001B - Prefill backtest UIs from canonical saved portfolio settings
5. CORE-001C - Migrate backtests and event comparison to unit-safe scenario/value handling
6. BT-003B - Add event-comparison drilldown and explanation of ranking outcomes
7. PORT-003 - Historical LTV visibility and export groundwork
8. BT-002 - Upgrade backtests to real daily options snapshots
9. BT-001C - Consolidate deterministic historical fixture/demo provider logic
10. CORE-001D - Clean up persistence and external boundaries for Decimal unit-safe types
11. EXEC-001 - Core user workflow
12. EXEC-002 - Execution capability
13. Remaining features