Vol Dashboard Documentation
This folder is the human-facing documentation set for the Vol Dashboard. Start here when onboarding to the system, operating production, or reviewing data accuracy.
Start Here
- User Journey — how an operator should move through the dashboard, what each screen answers, and how to interpret the story.
- Regime-Aware Trade Copilot Strategy — sponsor-facing strategy, six pillars, phased product direction, and decision matrix for the regime-aware copilot.
- Derivative Identity And Proxy Mapping — contract identity and proxy policy for exact, adjusted, fallback, SMA/OTC equivalent, unsupported, and unmapped trades.
- Source Authority Register — source-authority policy for execution marks, forward marks, terminal marks, realized P&L, estimates, proxies, and unavailable states.
- Data Ingestion Readiness Plan — reliable measurement backbone, durable ingestion jobs, coverage reason taxonomy, and provider-validation questions.
- Regime Model Specification — lookback policy, surface-location spot-vol detection, smile audit, risk-reversal divergence, danger zones, Model Lab provenance, and mixed-thesis trust states.
- Trade Copilot Evaluation Specification — accident-avoidance warnings, trade-action taxonomy, restructuring evaluator, and candidate filter diagnostics.
- SMA Ingestion Requirements — source field contract and derivative-equivalent mapping requirements for future SMA portfolio ingestion.
- System Overview — what the system does, source systems, runtime architecture, and production scope.
- Calculation Reference — formulas, units, assumptions, and known boundaries for displayed numbers.
- Decision Log — accepted product and data-integrity decisions that affect how calculations and analytics should be interpreted.
- Trade Performance Analytics — active metric contract and current production status for opportunity alignment, execution quality, outcome attribution, realized P&L boundaries, and data-quality states.
- Trade Performance Data Gaps — operator explanation of missing execution benchmarks, forward marks, null P&L, and the admin backfill commands.
- Trade Performance Discussion Guide — meeting guide for current data gaps, proxy assumptions, business decisions, and sign-off topics.
- Opportunity Alignment Rules — current signal point rules, label thresholds, confidence penalties, and business sign-off questions.
- Help Icon Documentation Audit — current audit of tooltip/help consistency, source-doc readiness, and the migration plan for structured help.
The in-app Reference help page is generated from this folder. When these docs change, re-run node scripts/generate-reference-docs.mjs so the frontend Reference pages carry the same content.
Recommended reading order: start with User Journey, then Regime-Aware Trade Copilot Strategy for the sponsor-facing direction, then Derivative Identity And Proxy Mapping and Source Authority Register for the source-quality gates, then the four preparatory specifications for ingestion, regime modelling, trade-copilot evaluation, and SMA ingestion. After that, read System Overview, Calculation Reference, then the performance docs and diagrams as needed.
Current Navigation Model
The dashboard top navigation is grouped around the operator journey:
| Navigation group | Primary question | Screens |
|---|---|---|
| Model | What is the current thesis, can we trust it, and what outcomes does it imply? | Model Explorer |
| Market Setup | What is priced, what is driving it, and does carry/leverage confirm it? | Overview, Flow, Futures & Carry, Yield Screener |
| Measurement | Did Alpha trade consistently with that setup, and are the source rows loaded? | Performance, Trade Book, Data Capture |
| Help | Where are the methodology docs? | Reference |
This structure is intentional: Model Explorer gives the thesis, trust diagnostics, and probability outcomes in one browsable model surface; Market Setup explains the opportunity drivers; Measurement checks Alpha behavior and source-row readiness against that context; Reference stays available as compact help rather than a primary analytical path.
Core Docs
| Document | Purpose |
|---|---|
| User Journey | First-class operator walkthrough: where to start, what to do, how to interpret each screen, and how the story deepens. |
| Regime-Aware Trade Copilot Strategy | Sponsor-facing strategy, six strategic pillars, staged roadmap, and decision matrix for turning the dashboard into a regime-aware trade copilot. |
| Derivative Identity And Proxy Mapping | Contract identity and proxy policy for exact listed, adjusted, standard-root fallback, SMA/OTC derivative-equivalent, unsupported, and unmapped trades. |
| Source Authority Register | Source-authority policy for deciding which marks, P&L values, estimates, proxies, and missing states may feed decision-grade outputs. |
| Data Ingestion Readiness Plan | Reliable measurement backbone, durable ingestion job contract, coverage reason taxonomy, and provider-validation questions for the next data-quality phase. |
| Regime Model Specification | Preparatory regime model contract for lookbacks, post-IBIT history, surface-location spot-vol, risk-reversal divergence, smile audit, conditional danger zones, Model Lab provenance, and mixed-thesis trust. |
| Trade Copilot Evaluation Specification | Preparatory contract for accident-avoidance warnings, trade-action taxonomy, restructuring comparison, and candidate-screen diagnostics. |
| SMA Ingestion Requirements | Field contract and mapping requirements for future SMA ingestion and derivative-equivalent trade representation. |
| System Overview | What the dashboard does, source systems, screens, runtime architecture, and current production scope. |
| Calculation Reference | Definitions, units, formulas, assumptions, and boundaries for the dashboard's calculations. |
| Trade Performance Analytics | Formal metric contract and current production boundary for trade analytics: inputs, formulas, units, quality states, no-data behavior, and which Performance questions are currently sourced. |
| Trade Performance Data Gaps | Practical explanation of unavailable MSTR/COIN execution benchmarks and forward marks, what users can ask for, and how to validate backfill states. |
| Trade Performance Discussion Guide | Business-facing discussion guide for data gaps, assumptions, current production numbers, and decisions needed before reading Performance as execution/outcome reporting. |
| Opportunity Alignment Rules | Current rule-based signal scoring methodology, label thresholds, confidence penalties, and sign-off questions for supportive/mixed/opposing labels. |
| Help Icon Documentation Audit | Documentation-first audit for making site-wide help icons structured, current, and consistent. |
| Decision Log | Accepted decisions for trade analytics, valuation boundaries, and future reviewer handoffs. |
| Operator Runbook | Production workflows for health checks, Alpha sync, sync-completeness diagnostics, snapshots, alerts, and missing-data triage. |
| UX Verification Plan | Browser walkthrough and operator story for validating the dashboard end to end. |
| Data Dictionary | Core database tables, important fields, units, and source semantics. |
| Deployment | Cloud Run deployment process, canonical URLs, required output, and never-do list. |
| Alpha Trade Sync | Detailed Alpha trade-feed configuration, semantics, and operator workflow. |
| Diagrams | Mermaid diagrams for system architecture and data flows. |
| GEX Flow | Focused GEX cache and regime calculation flow. |
Current Production Scope
- Deployment target: Google Cloud Run only.
- Backend canonical URL:
https://vol-backend-244916812493.us-east4.run.app - Frontend canonical URL:
https://vol-frontend-244916812493.us-east4.run.app - UAT frontend domain:
https://uat-vol.bitwiseinvestments.devafter Cloud Run domain mapping and DNS are applied. - Primary market data source: Amberdata.
- Internal trade source: Alpha option-trades export.
- Current Alpha production scope: portfolios
IMST,ICOI,include_pending=falseby default.
Important Boundaries
- Alpha trade sync is operator-triggered, not streaming.
- Frontend never calls Amberdata or Alpha directly.
- Browser never receives the Alpha API key.
- P&L, IV edge, and execution quality should remain blank when the dashboard lacks trustworthy marks, execution-time bid/ask quotes, traded-IV inputs, or authoritative realized-P&L data.
- Trade performance analytics should distinguish market/regime proxy context from instrument-level quote and outcome sources.
- Trade performance currently scores opportunity alignment from available Alpha trade-time context; execution quality and forward outcome P&L are shown only where sourced quote/mark inputs exist, smile context is intentionally not sourced for current Alpha MSTR/COIN rows, and realized P&L remains unavailable unless authoritative accounting/lifecycle inputs exist.
- Regime-aware copilot outputs should remain gated by source quality, proxy mapping, stationarity, and mixed-thesis confidence states; accident-avoidance warnings must be visibly distinct from sourced P&L or execution-quality reporting.
- Derivative identity and market/regime proxy context are separate. A BTC proxy can explain MSTR/COIN opportunity backdrop, but cannot validate MSTR/COIN execution marks, liquidity, or P&L.
- Source-authority gates are tracked in the Source Authority Register; direct, proxy, estimated, stale, pending, unavailable, unsupported, and not-entitled states must remain distinguishable.
- New trade-performance metrics must carry source and quality states; missing economics must not be displayed as zero.
- Model Diagnostics live GEX magnet/repeller levels must carry freshness state; stale or unavailable live levels should not be read as current strike signals.
- Data Capture is the operator entry point for checking persisted snapshot freshness, source timestamps, record counts, coverage gaps, and probability-readiness quality before trusting model pages.