Requirements Document
Introduction
The Market Maker Dashboard provides real-time and historical visualization of market maker performance, regime analysis, and trading recommendations. The dashboard is implemented as a static website that reads from historical metrics data stored in YAML files (collected by the Regime Management System per Requirement 15 in regime-management spec) and presents key information through interactive charts and status displays.
This spec focuses on the visualization and user interface aspects of the dashboard. The metrics collection functionality is defined in the regime-management spec (Requirement 15).
Glossary
- Dashboard: The static web-based visualization interface for market maker metrics
- Spot_Check_Dashboard: A standalone HTML file generated for each recommendation that visualizes all underlying analysis factors and decision data
- Static_Site_Generator: A tool that generates static HTML/CSS/JavaScript files from templates and data
- Metrics_Store: The file-based storage system containing historical YAML metric files (managed by Regime Management System)
- Regime: The current market state classification (RANGE_OK, RANGE_WEAK, TRANSITION, TREND)
- Grid_Analysis: Performance and operational status of trading grid levels
- Time_Series_Chart: A chart displaying data points over time
- Risk_Level: Classification of current risk (LOW, MEDIUM, HIGH, CRITICAL)
- Market_Metrics_File: Individual YAML files containing minute-by-minute price data and regime analysis for a specific market and time period
- Client_Side_Rendering: JavaScript code that runs in the browser to load and display data dynamically
Requirements
Requirement 1: Generate Static Dashboard Site
User Story: As a trader, I want a static website dashboard that can be viewed without a running web server, so that I can easily access my metrics from any browser.
Acceptance Criteria
- THE Dashboard SHALL generate static HTML, CSS, and JavaScript files
- THE Dashboard SHALL be viewable by opening the HTML file directly in a browser without requiring a web server
- WHEN the Dashboard is generated, THE System SHALL create all necessary assets (HTML, CSS, JavaScript, chart libraries) in a single output directory
- WHEN generating the Dashboard, THE System SHALL pre-process all YAML metric files and extract data needed for visualization into optimized JSON or JavaScript data structures
- WHEN pre-processing metrics, THE System SHALL include only the data required for each chart type to minimize file size
- THE Dashboard SHALL be regenerated automatically after each metrics collection cycle
- WHEN accessing the Dashboard, THE System SHALL serve files from the local filesystem or via a simple static file server
Requirement 2: Load Historical Metrics Data
User Story: As a trader, I want to view historical market maker metrics, so that I can analyze past performance and market conditions.
Acceptance Criteria
- WHEN generating the Dashboard, THE System SHALL scan the Metrics_Store directory structure for all available metric files
- WHEN metric files are found, THE System SHALL parse YAML files and extract pricing, regime, and grid data
- WHEN parsing fails for a file, THE System SHALL log the error and continue processing remaining files
- THE System SHALL support loading metrics from multiple dates and hours
- WHEN processing data, THE System SHALL preserve chronological ordering based on file timestamps
- WHEN the Dashboard loads in the browser, THE Client_Side_Rendering SHALL load pre-processed data files without needing to parse YAML
Requirement 3: Display Pricing Data
User Story: As a trader, I want to see price movements over time with minute-level granularity, so that I can understand market trends and volatility in detail.
Acceptance Criteria
- WHEN pricing data is loaded, THE Dashboard SHALL display a Time_Series_Chart showing price over time with minute-level granularity
- THE Dashboard SHALL plot opening, closing, high, and low prices for each hour
- WHEN grid configuration exists, THE Dashboard SHALL overlay grid bounds (upper and lower) on the price chart
- WHEN grid levels exist, THE Dashboard SHALL display individual grid level prices as horizontal lines
- WHEN displaying market metrics, THE Dashboard SHALL overlay regime classification data on price charts to show regime changes relative to price movements
- THE Dashboard SHALL support zooming and panning on the time axis
- WHEN hovering over a data point, THE Dashboard SHALL display detailed price information in a tooltip
Requirement 4: Visualize Regime Analysis
User Story: As a trader, I want to see regime classifications over time, so that I can understand market state transitions and confidence levels.
Acceptance Criteria
- WHEN regime data is loaded, THE Dashboard SHALL display regime verdict for each time period
- THE Dashboard SHALL use distinct colors for each regime type (RANGE_OK, RANGE_WEAK, TRANSITION, TREND)
- WHEN displaying regime data, THE Dashboard SHALL show confidence scores as a percentage
- THE Dashboard SHALL display regime strength (STRONG, MODERATE, WEAK) alongside the verdict
- WHEN regime changes occur, THE Dashboard SHALL visually highlight transition points
- THE Dashboard SHALL display range integrity, support strength, and resistance strength metrics
- THE Dashboard SHALL show competing verdicts with their weights when available
Requirement 5: Show Grid Performance Metrics
User Story: As a trader, I want to monitor grid trading performance and account balance, so that I can assess profitability and capital deployment.
Acceptance Criteria
- WHEN grid data is loaded, THE Dashboard SHALL display total profit and profit percentage
- THE Dashboard SHALL show the count of active trades and grid levels
- THE Dashboard SHALL display grid operational status (PRICE_ABOVE_RANGE, PRICE_BELOW_RANGE, PRICE_IN_RANGE)
- WHEN grid levels exist, THE Dashboard SHALL show how many buy levels are waiting and sell levels are active
- THE Dashboard SHALL display capital at risk and position health status
- WHEN displaying account metrics, THE Dashboard SHALL show time-series graphs of total balance, available balance, and deployed capital over time
- WHEN displaying grid metrics, THE Dashboard SHALL show charts of active grid count, total capital deployed, and profit/loss trends for each grid
Requirement 6: Display Risk Assessment and Recommendations
User Story: As a trader, I want to see current risk levels and recommendations, so that I can make informed trading decisions.
Acceptance Criteria
- WHEN risk data is loaded, THE Dashboard SHALL display the overall Risk_Level with appropriate color coding
- THE Dashboard SHALL list all identified risk factors for the current period
- THE Dashboard SHALL display actionable recommendations based on current market conditions
- WHEN Risk_Level is HIGH or CRITICAL, THE Dashboard SHALL prominently highlight the warning
- THE Dashboard SHALL show when the assessment was made and when the next review is recommended
Requirement 7: Support Time Range Selection
User Story: As a trader, I want to select different time ranges, so that I can focus on specific periods of interest.
Acceptance Criteria
- THE Dashboard SHALL provide controls to select start and end dates for data display
- WHEN a time range is selected, THE Dashboard SHALL filter all charts and displays to show only data within that range
- THE Dashboard SHALL support preset time ranges (Last 24 Hours, Last 7 Days, Last 30 Days, All Time)
- WHEN no data exists for a selected range, THE Dashboard SHALL display an informative message
- THE Dashboard SHALL update all visualizations simultaneously when the time range changes
Requirement 8: Provide Real-Time Data Updates
User Story: As a trader, I want the dashboard to automatically refresh with new data, so that I always see current information without manual intervention.
Acceptance Criteria
- THE Dashboard SHALL check for new metric files at regular intervals (configurable, default 60 seconds)
- WHEN new metric files are detected, THE Dashboard SHALL load and display the new data
- WHEN updating data, THE Dashboard SHALL preserve the user’s current view settings (zoom level, selected time range)
- THE Dashboard SHALL display the timestamp of the most recent data point
- THE Dashboard SHALL indicate when data is being refreshed with a visual indicator
Requirement 9: Support Multiple Markets
User Story: As a trader managing multiple trading pairs, I want to view metrics for different markets, so that I can monitor all my positions.
Acceptance Criteria
- THE Dashboard SHALL provide a market selector to switch between different trading pairs
- WHEN a market is selected, THE Dashboard SHALL load and display metrics specific to that market
- THE Dashboard SHALL support viewing multiple markets simultaneously in separate panels
- WHEN no data exists for a selected market, THE Dashboard SHALL display an informative message
- THE Dashboard SHALL display the list of available markets based on discovered metric files
Requirement 10: Export Data and Visualizations
User Story: As a trader, I want to export charts and data, so that I can share analysis with others or keep records.
Acceptance Criteria
- THE Dashboard SHALL provide an export button for each chart
- WHEN exporting a chart, THE Dashboard SHALL support PNG and SVG image formats
- THE Dashboard SHALL provide an option to export raw data as CSV or JSON
- WHEN exporting data, THE Dashboard SHALL include all visible data points in the current time range
- THE Dashboard SHALL include metadata (export timestamp, time range, symbol) in exported files
Requirement 11: Responsive Design
User Story: As a trader using multiple devices, I want the dashboard to work well on both desktop and mobile, so that I can monitor my positions from anywhere.
Acceptance Criteria
- WHEN charts are displayed, THE Dashboard SHALL use responsive design that works on both desktop and mobile devices
- WHEN viewed on mobile devices, THE Dashboard SHALL adapt layout to fit smaller screens
- WHEN viewed on desktop, THE Dashboard SHALL utilize available screen space efficiently
- THE Dashboard SHALL maintain readability and usability across different screen sizes
Requirement 12: Spot Check Dashboard for Recommendation Support
User Story: As a grid trader evaluating a recommendation, I want a detailed “spot check” dashboard that visualizes all the underlying market data and analysis factors that led to the recommendation, so that I can validate the system’s reasoning and make informed decisions.
Acceptance Criteria
- WHEN a recommendation is generated, THE Dashboard SHALL create a spot check data snapshot containing raw exchange data, analysis results, and configuration state
- WHEN storing spot check snapshots, THE Dashboard SHALL save them as JSON files to a dedicated spotchecks directory in the market-maker-data repository
- WHEN storing raw exchange data in snapshots, THE Dashboard SHALL preserve OHLCV candlestick data from KuCoin in its original form for all timeframes used in regime analysis (1m, 15m, 1h, 4h)
- WHEN storing 1-minute OHLCV data in snapshots, THE Dashboard SHALL include high and low values (not just close) to enable accurate grid level crossing detection and boundary violation analysis
- WHEN storing multi-timeframe candlestick data in snapshots, THE Dashboard SHALL preserve the complete OHLCV data (open, high, low, close, volume) for each timeframe to enable recalculation of TrendScore, MeanRevScore, VolScore, and gate evaluations
- WHEN storing analysis results in snapshots, THE Dashboard SHALL include all calculated regime scores, gate evaluations, discovered ranges, and competing verdicts as they were computed at recommendation time
- WHEN storing configuration in snapshots, THE Dashboard SHALL capture grid configuration parameters, thresholds, and system settings that were active at recommendation time
- WHEN naming spot check snapshot files, THE Dashboard SHALL use the format “spotcheck_{timestamp}{symbol}{recommendation_id}.json” to ensure uniqueness and traceability
- WHEN the static site is generated, THE Dashboard SHALL scan the spotchecks directory and generate an HTML page for each snapshot file
- WHEN generating spot check HTML pages, THE Dashboard SHALL use the same shared JavaScript libraries and CSS as the main dashboard to avoid versioning complexity
- WHEN a spot check snapshot includes a recommendation ID, THE Dashboard SHALL include a link to the corresponding decision record file in the market-maker-data repository
- WHEN displaying spot check data, THE Dashboard SHALL show comprehensive market analysis data for the analyzed time period
- WHEN displaying regime classification factors, THE Dashboard SHALL show time-series charts for mean reversion indicators including lag-1 autocorrelation, OU half-life, and z-score reversion rate
- WHEN displaying regime classification factors, THE Dashboard SHALL show time-series charts for directional persistence indicators including ADX, normalized slope, and trend strength
- WHEN displaying regime classification factors, THE Dashboard SHALL show time-series charts for range quality metrics including discovered range bounds, range ratio (amplitude/ATR), and efficiency ratio
- WHEN displaying regime classification factors, THE Dashboard SHALL show time-series charts for volatility state metrics including ATR percentage, volatility expansion/contraction, and Bollinger Band bandwidth
- WHEN displaying regime classification factors, THE Dashboard SHALL show time-series charts for volatility state metrics including ATR percentage, volatility expansion/contraction, and Bollinger Band bandwidth
- WHEN displaying discovered range analysis, THE Dashboard SHALL overlay discovered support/resistance levels on the price chart with visual indicators showing rejection frequency and range stability duration
- WHEN displaying grid comparison data, THE Dashboard SHALL show the relationship between discovered market range bounds and configured grid bounds (if a grid exists)
- WHEN a grid exists, THE Dashboard SHALL highlight price position relative to both discovered range and configured grid bounds
- WHEN grid restart gates are being evaluated, THE Dashboard SHALL display gate status for all three gates (Directional Energy Decay, Mean Reversion Return, Tradable Volatility) with pass/fail indicators
- WHEN displaying gate evaluation details, THE Dashboard SHALL show the specific metrics and thresholds for each gate component with visual indicators of whether each metric passes or fails
- WHEN displaying gate evaluation history, THE Dashboard SHALL show time-series data of gate status over the evaluation period to visualize gate stability
- WHEN displaying spot check data, THE Dashboard SHALL show minute-by-minute price data from the exchange for the analyzed period to provide granular price movement context
- WHEN displaying technical indicators, THE Dashboard SHALL overlay indicator values on price charts where appropriate (e.g., Bollinger Bands, moving averages, ATR bands)
- WHEN displaying regime verdict, THE Dashboard SHALL show the final classification (RANGE_OK, RANGE_WEAK, TRANSITION, TREND) with confidence score and supporting metrics
- WHEN displaying competing verdicts, THE Dashboard SHALL show alternative regime classifications with their weights and supporting data
- WHEN displaying spot check data, THE Dashboard SHALL provide export functionality for all charts and underlying data for external analysis
- WHEN a recommendation includes a proposed grid configuration, THE Dashboard SHALL visualize the proposed grid levels overlaid on the price chart with discovered range bounds
- WHEN displaying historical spot checks, THE Dashboard SHALL provide an index page listing all available spot check snapshots with links to their generated pages
- WHEN spot check data is incomplete or unavailable, THE Dashboard SHALL clearly indicate which metrics are missing and why
- WHEN displaying spot check visualizations, THE Dashboard SHALL use consistent color coding and visual language with the main dashboard for regime types and risk levels
- WHEN re-analyzing historical spot check data, THE Dashboard SHALL use the preserved raw exchange data from the snapshot to recalculate analysis with updated algorithms without requiring access to the exchange API
Requirement 13: Recent Recommendations List
User Story: As a grid trader, I want to see a list of recent recommendations on the main dashboard with links to their spot check pages, so that I can quickly access detailed analysis for any recommendation.
Acceptance Criteria
- WHEN the main dashboard is displayed, THE Dashboard SHALL show a “Recent Recommendations” section listing the most recent 20-30 recommendations
- WHEN displaying each recommendation in the list, THE Dashboard SHALL show timestamp, symbol, regime verdict, confidence score, action, and status
- WHEN a recommendation has a corresponding spot check snapshot, THE Dashboard SHALL provide a clickable link to the spot check dashboard page
- WHEN displaying recommendations, THE Dashboard SHALL use color coding consistent with regime types (RANGE_OK=green, RANGE_WEAK=yellow, TRANSITION=orange, TREND=red)
- WHEN the recommendations list is displayed, THE Dashboard SHALL support sorting by timestamp, symbol, verdict, or confidence
- WHEN the recommendations list is displayed, THE Dashboard SHALL support filtering by symbol, verdict type, or action type
- WHEN a user clicks on a recommendation row, THE Dashboard SHALL navigate to the corresponding spot check dashboard page
- WHEN hovering over a recommendation, THE Dashboard SHALL display a tooltip with quick preview of key metrics
- WHEN generating the recommendations list, THE Dashboard SHALL scan decision records and match them to spot check snapshots
- WHEN a decision record exists without a corresponding spot check snapshot, THE Dashboard SHALL still display the recommendation but indicate that detailed analysis is not available