0003 - Market Maker Dashboard: Spot Check Pages - Implementation Plan

Overview

Implement spot check page generation and visualizations for the market maker dashboard. This involves Python classes for scanning/parsing snapshots, Jinja2 templates for HTML generation, and JavaScript for chart visualizations.

Target Repo: repos/market-making Protocol: SPIDER

Prerequisites

Read the spec: codev/specs/0003-market-maker-dashboard-spot-checks.md
Understand existing dashboard structure in repos/market-making/dashboard/
Review StaticSiteGenerator class for integration patterns

Phase 1: Spot Check Scanner and Parser (Tasks 10.1, 10.2)

1.1 Create SpotCheckScanner class

File: dashboard/build/spotcheck_scanner.py

class SpotCheckScanner:
    def __init__(self, spotchecks_dir: Path):
        self.spotchecks_dir = spotchecks_dir
 
    def scan_spotcheck_directory(self) -> List[SpotCheckMetadata]:
        """Find all JSON snapshot files matching pattern spotcheck_*.json"""
 
    def index_by_timestamp(self) -> Dict[datetime, SpotCheckMetadata]:
        """Index snapshots by timestamp for chronological access"""
 
    def index_by_symbol(self) -> Dict[str, List[SpotCheckMetadata]]:
        """Index snapshots by trading symbol"""
 
    def match_to_decision_records(self, decision_records_dir: Path) -> Dict[str, str]:
        """Match snapshots to their decision record files"""

1.2 Create SpotCheckParser class

File: dashboard/build/spotcheck_parser.py

class SpotCheckParser:
    def parse_snapshot(self, filepath: Path) -> SpotCheckData:
        """Load and parse JSON snapshot file"""
 
    def validate_structure(self, data: dict) -> ValidationResult:
        """Validate snapshot has required fields"""
 
    def extract_raw_exchange_data(self, data: dict) -> Dict[str, List[OHLCV]]:
        """Extract OHLCV data for all timeframes (1m, 15m, 1h, 4h)"""
 
    def extract_analysis_results(self, data: dict) -> AnalysisResults:
        """Extract regime classification, gate evaluations, etc."""
 
    def extract_configuration(self, data: dict) -> ConfigSnapshot:
        """Extract grid config and system settings"""

1.3 Unit tests

File: dashboard/build/test_spotcheck_scanner_parser.py

Test scanning with mock directory structure
Test parsing sample snapshot JSON
Test validation catches missing/malformed data
Test indexing functions

Commit: [Spec 0003][Implement] Add SpotCheckScanner and SpotCheckParser

Phase 2: HTML Templates (Tasks 10.3, 10.4, 10.5)

2.1 Create templates directory and base layout

Directory: dashboard/templates/

File: dashboard/templates/base.html

Common HTML structure, CSS/JS includes
Shared header/footer

2.2 Create spot check page template

File: dashboard/templates/spotcheck.html

Sections:

Header: Timestamp, symbol, recommendation ID, verdict badge
Multi-timeframe charts: Container divs for 1m, 15m, 1h, 4h charts
Regime factors: Mean reversion, directional, range quality, volatility
Gate evaluations: 3 gates with pass/fail indicators
Grid comparison: Discovered range vs configured bounds
Configuration: Grid config, thresholds, settings
Decision record link: Link to raw decision file

2.3 Create spot check index template

File: dashboard/templates/spotcheck-index.html

Sortable table: timestamp, symbol, verdict, confidence, action
Filter controls for symbol, verdict type
Links to individual spot check pages
Regime color coding

2.4 Create SpotCheckGenerator class

File: dashboard/build/spotcheck_generator.py

class SpotCheckGenerator:
    def __init__(self, template_dir: Path, output_dir: Path):
        self.jinja_env = Environment(loader=FileSystemLoader(template_dir))
 
    def generate_spotcheck_page(self, snapshot: SpotCheckData, output_dir: Path) -> str:
        """Generate individual spot check HTML page"""
 
    def generate_index_page(self, all_snapshots: List[SpotCheckMetadata], output_dir: Path) -> str:
        """Generate index.html listing all spot checks"""
 
    def copy_shared_assets(self, output_dir: Path):
        """Copy CSS/JS from main dashboard"""

2.5 Unit tests

File: dashboard/build/test_spotcheck_generator.py

Test page generation with mock data
Test index generation with multiple snapshots
Test asset copying

Commit: [Spec 0003][Implement] Add spot check templates and generator

Phase 3: JavaScript Visualizations (Tasks 11.1-11.4)

3.1 Create SpotCheckChartManager class

File: dashboard/js/spotcheck-chart-manager.js

class SpotCheckChartManager {
    constructor(chartConfig) {
        this.regimeColors = { /* consistent with main dashboard */ };
    }
 
    // Multi-timeframe price charts
    renderMultiTimeframeCharts(rawExchangeData, containers) {}
 
    // Regime factor charts
    renderMeanReversionFactors(container, indicators) {}
    renderDirectionalPersistenceFactors(container, indicators) {}
    renderRangeQualityFactors(container, indicators) {}
    renderVolatilityFactors(container, indicators) {}
 
    // Discovered range overlay
    renderDiscoveredRange(priceChart, discoveredRange) {}
    renderRejectionFrequency(priceChart, levels) {}
 
    // Gate evaluations
    renderGateEvaluations(container, gates) {}
    renderGateTimeSeries(container, gateHistory) {}
 
    // Competing verdicts
    renderCompetingVerdicts(container, verdicts) {}
 
    // Grid comparison
    renderGridComparison(priceChart, discoveredRange, gridConfig) {}
 
    // Technical indicators
    renderTechnicalIndicators(priceChart, indicators) {}
}

3.2 Extend CSS for spot check pages

File: dashboard/css/spotcheck.css

Gate evaluation styling (pass/fail indicators)
Verdict badges with regime colors
Chart container layouts
Responsive design rules

3.3 JavaScript tests

File: dashboard/test-spotcheck-chart-manager.js

Test chart rendering with mock data
Test color scheme consistency
Test overlay rendering

Commit: [Spec 0003][Implement] Add SpotCheckChartManager and CSS

Phase 4: Recommendations Scanner (Task 12.1)

4.1 Create RecommendationsScanner class

File: dashboard/build/recommendations_scanner.py

class RecommendationsScanner:
    def scan_decision_records(self, directory: Path) -> List[DecisionRecord]:
        """Scan decision record files"""
 
    def match_to_spotchecks(self, spotchecks: List[SpotCheckMetadata]) -> Dict[str, str]:
        """Match decision records to spot check snapshots"""
 
    def extract_metadata(self, record: DecisionRecord) -> RecommendationMetadata:
        """Extract display metadata from decision record"""
 
    def get_recent_recommendations(self, limit: int = 30) -> List[RecommendationMetadata]:
        """Get most recent recommendations for dashboard display"""

4.2 Unit tests

File: dashboard/build/test_recommendations_scanner.py

Commit: [Spec 0003][Implement] Add RecommendationsScanner

Phase 5: Integration (StaticSiteGenerator)

5.1 Update StaticSiteGenerator

File: dashboard/build/static_site_generator.py

Add to generate_site():

Call SpotCheckScanner to discover snapshots
Call SpotCheckGenerator to create spot check pages
Generate spot check index page
Include recent recommendations in main dashboard context

5.2 Integration tests

File: dashboard/build/test_integration.py

Test full site generation with spot check pages
Test links between main dashboard and spot checks

Commit: [Spec 0003][Implement] Integrate spot checks into StaticSiteGenerator

Phase 6: Defend (Tests)

6.1 Ensure all unit tests pass

cd dashboard && python -m pytest build/

6.2 Manual verification

Generate site with sample spot check data
Verify all pages render correctly
Test filter/sort on index page
Verify chart rendering in browser

Commit: [Spec 0003][Defend] Add comprehensive test coverage

Phase 7: Review

7.1 Create review document

File: codev/reviews/0003-market-maker-dashboard-spot-checks.md

Document:

Implementation decisions
Deviations from spec (if any)
Lessons learned

7.2 Run 3-way review

consult --model gemini --type pr-ready pr $PR_NUMBER &
consult --model codex --type pr-ready pr $PR_NUMBER &
consult --model claude --type pr-ready pr $PR_NUMBER &
wait

7.3 Create PR

gh pr create --title "[Spec 0003] Market Maker Dashboard: Spot Check Pages" --body "..."

Commit: [Spec 0003][Review] Add implementation review

Files to Create/Modify

New Files

File	Description
`dashboard/build/spotcheck_scanner.py`	Scan and index snapshot files
`dashboard/build/spotcheck_parser.py`	Parse snapshot JSON
`dashboard/build/spotcheck_generator.py`	Generate HTML pages
`dashboard/build/recommendations_scanner.py`	Scan decision records
`dashboard/templates/base.html`	Base HTML template
`dashboard/templates/spotcheck.html`	Spot check page template
`dashboard/templates/spotcheck-index.html`	Index page template
`dashboard/js/spotcheck-chart-manager.js`	Chart visualizations
`dashboard/css/spotcheck.css`	Spot check styling
`dashboard/build/test_spotcheck_scanner_parser.py`	Scanner/parser tests
`dashboard/build/test_spotcheck_generator.py`	Generator tests
`dashboard/build/test_recommendations_scanner.py`	Recommendations tests

Modified Files

File	Changes
`dashboard/build/static_site_generator.py`	Add spot check generation
`dashboard/build/__init__.py`	Export new classes

Acceptance Criteria

Notes

Spot check data is in market-maker-data repo, not market-making
The builder will need read access to sample snapshot files for testing
Reuse regimeColors from existing chart-manager.js for consistency

Techcle Wiki

Explorer

Plan