620 lines
28 KiB
Markdown
620 lines
28 KiB
Markdown
# 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
|
|
|
|
### 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
|