gogo2/.kiro/specs/1.multi-modal-trading-system/design.md

# Multi-Modal Trading System Design Document

## Overview

The Multi-Modal Trading System is designed as an advanced algorithmic trading platform that combines Convolutional Neural Networks (CNN) and Reinforcement Learning (RL) models orchestrated by a decision-making module. The system processes multi-timeframe and multi-symbol market data (primarily ETH and BTC) to generate trading actions.

This design document outlines the architecture, components, data flow, and implementation details for the system based on the requirements and existing codebase.

## Architecture

The system follows a modular architecture with clear separation of concerns:

```mermaid
graph TD
    A[Data Provider] --> B[Data Processor] (calculates pivot points)
    B --> C[CNN Model]
    B --> D[RL(DQN) Model]
    C --> E[Orchestrator]
    D --> E
    E --> F[Trading Executor]
    E --> G[Dashboard]
    F --> G
    H[Risk Manager] --> F
    H --> G
```

### Key Components

1. **Data Provider**: Centralized component responsible for collecting, processing, and distributing market data from multiple sources.
2. **Data Processor**: Processes raw market data, calculates technical indicators, and identifies pivot points.
3. **CNN Model**: Analyzes patterns in market data and predicts pivot points across multiple timeframes.
4. **RL Model**: Learns optimal trading strategies based on market data and CNN predictions.
5. **Orchestrator**: Makes final trading decisions based on inputs from both CNN and RL models.
6. **Trading Executor**: Executes trading actions through brokerage APIs.
7. **Risk Manager**: Implements risk management features like stop-loss and position sizing.
8. **Dashboard**: Provides a user interface for monitoring and controlling the system.

## Components and Interfaces

### 1. Data Provider Backbone - Multi-Layered Architecture

The Data Provider backbone is the foundation of the system, implemented as a multi-layered architecture with clear separation of concerns:

#### Architecture Layers

```
┌─────────────────────────────────────────────────────────────┐
│                    COBY System (Standalone)                  │
│  Multi-Exchange Aggregation │ TimescaleDB │ Redis Cache     │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│              Core DataProvider (core/data_provider.py)       │
│  Automatic Maintenance │ Williams Pivots │ COB Integration  │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│      StandardizedDataProvider (core/standardized_data_provider.py) │
│  BaseDataInput │ ModelOutputManager │ Unified Interface     │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                    Models (CNN, RL, etc.)                    │
└─────────────────────────────────────────────────────────────┘
```

#### Layer 1: COBY System (Multi-Exchange Aggregation)

**Purpose**: Standalone system for comprehensive multi-exchange data collection and storage

**Key Components**:
- **Exchange Connectors**: Binance, Coinbase, Kraken, Huobi, Bitfinex, KuCoin
- **TimescaleDB Storage**: Optimized time-series data persistence
- **Redis Caching**: High-performance data caching layer
- **REST API**: HTTP endpoints for data access
- **WebSocket Server**: Real-time data distribution
- **Monitoring**: Performance metrics, memory monitoring, health checks

**Data Models**:
- `OrderBookSnapshot`: Standardized order book data
- `TradeEvent`: Individual trade events
- `PriceBuckets`: Aggregated price bucket data
- `HeatmapData`: Visualization-ready heatmap data
- `ConnectionStatus`: Exchange connection monitoring

**Current Status**:  Fully implemented and operational

#### Layer 2: Core DataProvider (Real-Time Trading Operations)

**Purpose**: High-performance real-time data provider for trading operations

**Key Classes**:
- **DataProvider**: Central class managing data collection, processing, and distribution
- **EnhancedCOBWebSocket**: Real-time Binance WebSocket integration
- **WilliamsMarketStructure**: Recursive pivot point calculation
- **RealTimeTickAggregator**: Tick-to-OHLCV aggregation
- **COBIntegration**: COB data collection and aggregation

**Key Features**:
1. **Automatic Data Maintenance**:
   - Background worker updating data every half-candle period
   - 1500 candles cached per symbol/timeframe
   - Automatic fallback between Binance and MEXC
   - Rate limiting and error handling

2. **Williams Market Structure Pivot Points**:
   - Recursive pivot detection with 5 levels
   - Monthly 1s data analysis for comprehensive context
   - Pivot-based normalization bounds (PivotBounds)
   - Support/resistance level tracking

3. **COB Integration**:
   - EnhancedCOBWebSocket with multiple Binance streams:
     - `depth@100ms`: High-frequency order book updates
     - `ticker`: 24hr statistics and volume
     - `aggTrade`: Large order detection
   - 1s COB aggregation with price buckets ($1 ETH, $10 BTC)
   - Multi-timeframe imbalance MA (1s, 5s, 15s, 60s)
   - 30-minute raw tick buffer (180,000 ticks)

4. **Centralized Data Distribution**:
   - Subscriber management with callbacks
   - Thread-safe data access with locks
   - Performance tracking per subscriber
   - Tick buffers (1000 ticks per symbol)

**Data Structures**:
- `MarketTick`: Standardized tick data
- `PivotBounds`: Pivot-based normalization bounds
- `DataSubscriber`: Subscriber information
- `SimplePivotLevel`: Fallback pivot structure

**Current Status**:  Fully implemented with ongoing enhancements

#### Layer 3: StandardizedDataProvider (Unified Model Interface)

**Purpose**: Provide standardized, validated data in unified format for all models

**Key Classes**:
- **StandardizedDataProvider**: Extends DataProvider with unified interface
- **ModelOutputManager**: Centralized storage for cross-model feeding
- **BaseDataInput**: Standardized input format for all models
- **COBData**: Comprehensive COB data structure
- **ModelOutput**: Extensible output format

**Key Features**:
1. **Unified Data Format (BaseDataInput)**:
   ```python
   @dataclass
   class BaseDataInput:
       symbol: str
       timestamp: datetime
       ohlcv_1s: List[OHLCVBar]  # 300 frames
       ohlcv_1m: List[OHLCVBar]  # 300 frames
       ohlcv_1h: List[OHLCVBar]  # 300 frames
       ohlcv_1d: List[OHLCVBar]  # 300 frames
       btc_ohlcv_1s: List[OHLCVBar]  # 300 frames
       cob_data: Optional[COBData]
       technical_indicators: Dict[str, float]
       pivot_points: List[PivotPoint]
       last_predictions: Dict[str, ModelOutput]
       market_microstructure: Dict[str, Any]
   ```

2. **COB Data Structure**:
   - ±20 price buckets around current price
   - Bid/ask volumes and imbalances per bucket
   - MA (1s, 5s, 15s, 60s) of imbalances for ±5 buckets
   - Volume-weighted prices within buckets
   - Order flow metrics

3. **Model Output Management**:
   - Extensible ModelOutput format supporting all model types
   - Cross-model feeding with hidden states
   - Historical output storage (1000 entries)
   - Efficient query by model_name, symbol, timestamp

4. **Data Validation**:
   - Minimum 100 frames per timeframe
   - Non-null COB data validation
   - Data completeness scoring
   - Validation before model inference

**Current Status**:  Implemented with enhancements needed for heatmap integration

#### Implementation Details

**Existing Strengths**:
-  Robust automatic data maintenance with background workers
-  Williams Market Structure with 5-level pivot analysis
-  Real-time COB streaming with multiple Binance streams
-  Thread-safe data access and subscriber management
-  Comprehensive error handling and fallback mechanisms
-  Pivot-based normalization for improved model training
-  Centralized model output storage for cross-feeding

**Areas for Enhancement**:
-  Unified integration between COBY and core DataProvider
-  COB heatmap matrix generation for model inputs
-  Configurable price ranges for COB imbalance calculation
-  Comprehensive data quality scoring and monitoring
-  Missing data interpolation strategies
-  Enhanced validation with detailed error reporting

### Standardized Model Input/Output Format

#### Base Input Format (BaseDataInput)

All models receive data through `StandardizedDataProvider.get_base_data_input()` which returns:

```python
@dataclass
class BaseDataInput:
    """Unified base data input for all models"""
    symbol: str                                    # Primary symbol (e.g., 'ETH/USDT')
    timestamp: datetime                            # Current timestamp
    
    # OHLCV Data (300 frames each)
    ohlcv_1s: List[OHLCVBar]                      # 300 x 1-second bars
    ohlcv_1m: List[OHLCVBar]                      # 300 x 1-minute bars
    ohlcv_1h: List[OHLCVBar]                      # 300 x 1-hour bars
    ohlcv_1d: List[OHLCVBar]                      # 300 x 1-day bars
    btc_ohlcv_1s: List[OHLCVBar]                  # 300 x 1-second BTC bars
    
    # COB Data
    cob_data: Optional[COBData]                    # COB with ±20 buckets + MA
    
    # Technical Analysis
    technical_indicators: Dict[str, float]         # RSI, MACD, Bollinger, etc.
    pivot_points: List[PivotPoint]                 # Williams Market Structure pivots
    
    # Cross-Model Feeding
    last_predictions: Dict[str, ModelOutput]       # Outputs from all models
    
    # Market Microstructure
    market_microstructure: Dict[str, Any]          # Order flow, liquidity, etc.
    
    # Optional: COB Heatmap (for visualization and advanced models)
    cob_heatmap_times: Optional[List[datetime]]    # Heatmap time axis
    cob_heatmap_prices: Optional[List[float]]      # Heatmap price axis
    cob_heatmap_values: Optional[np.ndarray]       # Heatmap matrix (time x price)
```

**OHLCVBar Structure**:
```python
@dataclass
class OHLCVBar:
    symbol: str
    timestamp: datetime
    open: float
    high: float
    low: float
    close: float
    volume: float
    timeframe: str
    indicators: Dict[str, float]  # Technical indicators for this bar
```

**COBData Structure**:
```python
@dataclass
class COBData:
    symbol: str
    timestamp: datetime
    current_price: float
    bucket_size: float                             # $1 for ETH, $10 for BTC
    
    # Price Buckets (±20 around current price)
    price_buckets: Dict[float, Dict[str, float]]   # {price: {bid_vol, ask_vol, ...}}
    bid_ask_imbalance: Dict[float, float]          # {price: imbalance_ratio}
    volume_weighted_prices: Dict[float, float]     # {price: VWAP}
    
    # Moving Averages of Imbalance (±5 buckets)
    ma_1s_imbalance: Dict[float, float]            # 1-second MA
    ma_5s_imbalance: Dict[float, float]            # 5-second MA
    ma_15s_imbalance: Dict[float, float]           # 15-second MA
    ma_60s_imbalance: Dict[float, float]           # 60-second MA
    
    # Order Flow Metrics
    order_flow_metrics: Dict[str, float]           # Aggressive buy/sell ratios, etc.
```

#### Base Output Format (ModelOutput)

All models output predictions through standardized `ModelOutput`:

```python
@dataclass
class ModelOutput:
    """Extensible model output format supporting all model types"""
    model_type: str                                # 'cnn', 'rl', 'lstm', 'transformer'
    model_name: str                                # Specific model identifier
    symbol: str
    timestamp: datetime
    confidence: float                              # Overall confidence (0.0 to 1.0)
    
    # Model-Specific Predictions
    predictions: Dict[str, Any]                    # Flexible prediction format
    
    # Cross-Model Feeding
    hidden_states: Optional[Dict[str, Any]]        # For feeding to other models
    
    # Extensibility
    metadata: Dict[str, Any]                       # Additional model-specific info
```

**Standard Prediction Fields**:
- `action`: 'BUY', 'SELL', or 'HOLD'
- `action_confidence`: Confidence in the action (0.0 to 1.0)
- `direction_vector`: Price movement direction (-1.0 to 1.0)
- `direction_confidence`: Confidence in direction (0.0 to 1.0)
- `probabilities`: Dict of action probabilities {'BUY': 0.3, 'SELL': 0.2, 'HOLD': 0.5}

**Example CNN Output**:
```python
ModelOutput(
    model_type='cnn',
    model_name='williams_cnn_v2',
    symbol='ETH/USDT',
    timestamp=datetime.now(),
    confidence=0.85,
    predictions={
        'action': 'BUY',
        'action_confidence': 0.85,
        'pivot_points': [...],  # Predicted pivot points
        'direction_vector': 0.7,  # Upward movement
        'direction_confidence': 0.82
    },
    hidden_states={
        'conv_features': tensor(...),
        'lstm_hidden': tensor(...)
    },
    metadata={'model_version': '2.1', 'training_date': '2025-01-08'}
)
```

**Example RL Output**:
```python
ModelOutput(
    model_type='rl',
    model_name='dqn_agent_v1',
    symbol='ETH/USDT',
    timestamp=datetime.now(),
    confidence=0.78,
    predictions={
        'action': 'HOLD',
        'action_confidence': 0.78,
        'q_values': {'BUY': 0.45, 'SELL': 0.32, 'HOLD': 0.78},
        'expected_reward': 0.023,
        'direction_vector': 0.1,
        'direction_confidence': 0.65
    },
    hidden_states={
        'state_value': 0.56,
        'advantage_values': [0.12, -0.08, 0.22]
    },
    metadata={'epsilon': 0.1, 'replay_buffer_size': 10000}
)
```

### 2. CNN Model

The CNN Model is responsible for analyzing patterns in market data and predicting pivot points across multiple timeframes.

#### Key Classes and Interfaces

- **CNNModel**: Main class for the CNN model.
- **PivotPointPredictor**: Interface for predicting pivot points.
- **CNNTrainer**: Class for training the CNN model.
- ***INPUTS***: COB+OHCLV+Old Pivots (5 levels of pivots)
- ***OUTPUTS***: next pivot point for each level as price-time vector. (can be plotted as trend line) + suggested trade action (BUY/SELL)

#### Implementation Details

The CNN Model will:
- Accept multi-timeframe and multi-symbol data as input
- Output predicted pivot points for each timeframe (1s, 1m, 1h, 1d)
- Provide confidence scores for each prediction
- Make hidden layer states available for the RL model

Architecture:
- Input layer: Multi-channel input for different timeframes and symbols
- Convolutional layers: Extract patterns from time series data
- LSTM/GRU layers: Capture temporal dependencies
- Attention mechanism: Focus on relevant parts of the input
- Output layer: Predict pivot points and confidence scores

Training:
- Use programmatically calculated pivot points as ground truth
- Train on historical data
- Update model when new pivot points are detected
- Use backpropagation to optimize weights

### 3. RL Model

The RL Model is responsible for learning optimal trading strategies based on market data and CNN predictions.

#### Key Classes and Interfaces

- **RLModel**: Main class for the RL model.
- **TradingActionGenerator**: Interface for generating trading actions.
- **RLTrainer**: Class for training the RL model.

#### Implementation Details

The RL Model will:
- Accept market data, CNN model predictions (output), and CNN hidden layer states as input
- Output trading action recommendations (buy/sell)
- Provide confidence scores for each action
- Learn from past experiences to adapt to the current market environment

Architecture:
- State representation: Market data, CNN model predictions (output), CNN hidden layer states
- Action space: Buy, Sell
- Reward function: PnL, risk-adjusted returns
- Policy network: Deep neural network
- Value network: Estimate expected returns

Training:
- Use reinforcement learning algorithms (DQN, PPO, A3C)
- Train on historical data
- Update model based on trading outcomes
- Use experience replay to improve sample efficiency

### 4. Orchestrator

The Orchestrator serves as the central coordination hub of the multi-modal trading system, responsible for data subscription management, model inference coordination, output storage, training pipeline orchestration, and inference-training feedback loop management.

#### Key Classes and Interfaces

- **Orchestrator**: Main class for the orchestrator.
- **DataSubscriptionManager**: Manages subscriptions to multiple data streams with different refresh rates.
- **ModelInferenceCoordinator**: Coordinates inference across all models.
- **ModelOutputStore**: Stores and manages model outputs for cross-model feeding.
- **TrainingPipelineManager**: Manages training pipelines for all models.
- **DecisionMaker**: Interface for making trading decisions.
- **MoEGateway**: Mixture of Experts gateway for model integration.

#### Core Responsibilities

##### 1. Data Subscription and Management

The Orchestrator subscribes to the Data Provider and manages multiple data streams with varying refresh rates:

- **10Hz COB (Cumulative Order Book) Data**: High-frequency order book updates for real-time market depth analysis
- **OHLCV Data**: Traditional candlestick data at multiple timeframes (1s, 1m, 1h, 1d)
- **Market Tick Data**: Individual trade executions and price movements
- **Technical Indicators**: Calculated indicators that update at different frequencies
- **Pivot Points**: Market structure analysis data

**Data Stream Management**:
- Maintains separate buffers for each data type with appropriate retention policies
- Ensures thread-safe access to data streams from multiple models
- Implements intelligent caching to serve "last updated" data efficiently
- Maintains full base dataframe that stays current for any model requesting data
- Handles data synchronization across different refresh rates

**Enhanced 1s Timeseries Data Combination**:
- Combines OHLCV data with COB (Cumulative Order Book) data for 1s timeframes
- Implements price bucket aggregation: ±20 buckets around current price
  - ETH: $1 bucket size (e.g., $3000-$3040 range = 40 buckets) when current price is 3020
  - BTC: $10 bucket size (e.g., $50000-$50400 range = 40 buckets) when price is 50200
- Creates unified base data input that includes:
  - Traditional OHLCV metrics (Open, High, Low, Close, Volume)
  - Order book depth and liquidity at each price level
  - Bid/ask imbalances for the +-5 buckets with Moving Averages for 5,15, and 60s
  - Volume-weighted average prices within buckets
  - Order flow dynamics and market microstructure data

##### 2. Model Inference Coordination

The Orchestrator coordinates inference across all models in the system:

**Inference Pipeline**:
- Triggers model inference when relevant data updates occur
- Manages inference scheduling based on data availability and model requirements
- Coordinates parallel inference execution for independent models
- Handles model dependencies (e.g., RL model waiting for CNN hidden states)

**Model Input Management**:
- Assembles appropriate input data for each model based on their requirements
- Ensures models receive the most current data available at inference time
- Manages feature engineering and data preprocessing for each model
- Handles different input formats and requirements across models

##### 3. Model Output Storage and Cross-Feeding

The Orchestrator maintains a centralized store for all model outputs and manages cross-model data feeding:

**Output Storage**:
- Stores CNN predictions, confidence scores, and hidden layer states
- Stores RL action recommendations and value estimates
- Stores outputs from all models in extensible format supporting future models (LSTM, Transformer, etc.)
- Maintains historical output sequences for temporal analysis
- Implements efficient retrieval mechanisms for real-time access
- Uses standardized ModelOutput format for easy extension and cross-model compatibility

**Cross-Model Feeding**:
- Feeds CNN hidden layer states into RL model inputs
- Provides CNN predictions as context for RL decision-making
- Includes "last predictions" from each available model as part of base data input
- Stores model outputs that become inputs for subsequent inference cycles
- Manages circular dependencies and feedback loops between models
- Supports dynamic model addition without requiring system architecture changes

##### 4. Training Pipeline Management

The Orchestrator coordinates training for all models by managing the prediction-result feedback loop:

**Training Coordination**:
- Calls each model's training pipeline when new inference results are available
- Provides previous predictions alongside new results for supervised learning
- Manages training data collection and labeling
- Coordinates online learning updates based on real-time performance

**Training Data Management**:
- Maintains training datasets with prediction-result pairs
- Implements data quality checks and filtering
- Manages training data retention and archival policies
- Provides training data statistics and monitoring

**Performance Tracking**:
- Tracks prediction accuracy for each model over time
- Monitors model performance degradation and triggers retraining
- Maintains performance metrics for model comparison and selection

**Training progress and checkpoints persistance**
- it uses the checkpoint manager to store check points of each model over time as training progresses and we have improvements 
- checkpoint manager has capability to ensure only top 5 to 10 best checkpoints are stored for each model deleting the least performant ones. it stores metadata along the CPs to decide the performance
- we automatically load the best CP at startup if we have stored ones

##### 5. Inference Data Validation and Storage

The Orchestrator implements comprehensive inference data validation and persistent storage:

**Input Data Validation**:
- Validates complete OHLCV dataframes for all required timeframes before inference
- Checks input data dimensions against model requirements
- Logs missing components and prevents prediction on incomplete data
- Raises validation errors with specific details about expected vs actual dimensions

**Inference History Storage**:
- Stores complete input data packages with each prediction in persistent storage
- Includes timestamp, symbol, input features, prediction outputs, confidence scores, and model internal states
- Maintains compressed storage to minimize footprint while preserving accessibility
- Implements efficient query mechanisms by symbol, timeframe, and date range

**Storage Management**:
- Applies configurable retention policies to manage storage limits
- Archives or removes oldest entries when limits are reached
- Prioritizes keeping most recent and valuable training examples during storage pressure
- Provides data completeness metrics and validation results in logs

##### 6. Inference-Training Feedback Loop

The Orchestrator manages the continuous learning cycle through inference-training feedback:

**Prediction Outcome Evaluation**:
- Evaluates prediction accuracy against actual price movements after sufficient time has passed
- Creates training examples using stored inference data paired with actual market outcomes
- Feeds prediction-result pairs back to respective models for learning

**Adaptive Learning Signals**:
- Provides positive reinforcement signals for accurate predictions
- Delivers corrective training signals for inaccurate predictions to help models learn from mistakes
- Retrieves last inference data for each model to compare predictions against actual outcomes

**Continuous Improvement Tracking**:
- Tracks and reports accuracy improvements or degradations over time
- Monitors model learning progress through the feedback loop
- Alerts administrators when data flow issues are detected with specific error details and remediation suggestions

##### 5. Decision Making and Trading Actions

Beyond coordination, the Orchestrator makes final trading decisions:

**Decision Integration**:
- Combines outputs from CNN and RL models using Mixture of Experts approach
- Applies confidence-based filtering to avoid uncertain trades
- Implements configurable thresholds for buy/sell decisions
- Considers market conditions and risk parameters

#### Implementation Details

**Architecture**:
```python
class Orchestrator:
    def __init__(self):
        self.data_subscription_manager = DataSubscriptionManager()
        self.model_inference_coordinator = ModelInferenceCoordinator()
        self.model_output_store = ModelOutputStore()
        self.training_pipeline_manager = TrainingPipelineManager()
        self.decision_maker = DecisionMaker()
        self.moe_gateway = MoEGateway()
    
    async def run(self):
        # Subscribe to data streams
        await self.data_subscription_manager.subscribe_to_data_provider()
        
        # Start inference coordination loop
        await self.model_inference_coordinator.start()
        
        # Start training pipeline management
        await self.training_pipeline_manager.start()
```

**Data Flow Management**:
- Implements event-driven architecture for data updates
- Uses async/await patterns for non-blocking operations
- Maintains data freshness timestamps for each stream
- Implements backpressure handling for high-frequency data

**Model Coordination**:
- Manages model lifecycle (loading, inference, training, updating)
- Implements model versioning and rollback capabilities
- Handles model failures and fallback mechanisms
- Provides model performance monitoring and alerting

**Training Integration**:
- Implements incremental learning strategies
- Manages training batch composition and scheduling
- Provides training progress monitoring and control
- Handles training failures and recovery

### 5. Trading Executor

The Trading Executor is responsible for executing trading actions through brokerage APIs.

#### Key Classes and Interfaces

- **TradingExecutor**: Main class for the trading executor.
- **BrokerageAPI**: Interface for interacting with brokerages.
- **OrderManager**: Class for managing orders.

#### Implementation Details

The Trading Executor will:
- Accept trading actions from the orchestrator
- Execute orders through brokerage APIs
- Manage order lifecycle
- Handle errors and retries
- Provide feedback on order execution

Supported brokerages:
- MEXC
- Binance
- Bybit (future extension)

Order types:
- Market orders
- Limit orders
- Stop-loss orders

### 6. Risk Manager

The Risk Manager is responsible for implementing risk management features like stop-loss and position sizing.

#### Key Classes and Interfaces

- **RiskManager**: Main class for the risk manager.
- **StopLossManager**: Class for managing stop-loss orders.
- **PositionSizer**: Class for determining position sizes.

#### Implementation Details

The Risk Manager will:
- Implement configurable stop-loss functionality
- Implement configurable position sizing based on risk parameters
- Implement configurable maximum drawdown limits
- Provide real-time risk metrics
- Provide alerts for high-risk situations

Risk parameters:
- Maximum position size
- Maximum drawdown
- Risk per trade
- Maximum leverage

### 7. Dashboard

The Dashboard provides a user interface for monitoring and controlling the system.

#### Key Classes and Interfaces

- **Dashboard**: Main class for the dashboard.
- **ChartManager**: Class for managing charts.
- **ControlPanel**: Class for managing controls.

#### Implementation Details

The Dashboard will:
- Display real-time market data for all symbols and timeframes
- Display OHLCV charts for all timeframes
- Display CNN pivot point predictions and confidence levels
- Display RL and orchestrator trading actions and confidence levels
- Display system status and model performance metrics
- Provide start/stop toggles for all system processes
- Provide sliders to adjust buy/sell thresholds for the orchestrator

Implementation:
- Web-based dashboard using Flask/Dash
- Real-time updates using WebSockets
- Interactive charts using Plotly
- Server-side processing for all models

## Data Models

### Market Data

```python
@dataclass
class MarketTick:
    symbol: str
    timestamp: datetime
    price: float
    volume: float
    quantity: float
    side: str  # 'buy' or 'sell'
    trade_id: str
    is_buyer_maker: bool
    raw_data: Dict[str, Any] = field(default_factory=dict)
```

### OHLCV Data

```python
@dataclass
class OHLCVBar:
    symbol: str
    timestamp: datetime
    open: float
    high: float
    low: float
    close: float
    volume: float
    timeframe: str
    indicators: Dict[str, float] = field(default_factory=dict)
```

### Pivot Points

```python
@dataclass
class PivotPoint:
    symbol: str
    timestamp: datetime
    price: float
    type: str  # 'high' or 'low'
    level: int  # Pivot level (1, 2, 3, etc.)
    confidence: float = 1.0
```

### Trading Actions

```python
@dataclass
class TradingAction:
    symbol: str
    timestamp: datetime
    action: str  # 'buy' or 'sell'
    confidence: float
    source: str  # 'rl', 'cnn', 'orchestrator'
    price: Optional[float] = None
    quantity: Optional[float] = None
    reason: Optional[str] = None
```

### Model Predictions

```python
@dataclass
class ModelOutput:
    """Extensible model output format supporting all model types"""
    model_type: str  # 'cnn', 'rl', 'lstm', 'transformer', 'orchestrator'
    model_name: str  # Specific model identifier
    symbol: str
    timestamp: datetime
    confidence: float
    predictions: Dict[str, Any]  # Model-specific predictions
    hidden_states: Optional[Dict[str, Any]] = None  # For cross-model feeding
    metadata: Dict[str, Any] = field(default_factory=dict)  # Additional info
```

```python
@dataclass
class CNNPrediction:
    symbol: str
    timestamp: datetime
    pivot_points: List[PivotPoint]
    hidden_states: Dict[str, Any]
    confidence: float
```

```python
@dataclass
class RLPrediction:
    symbol: str
    timestamp: datetime
    action: str  # 'buy' or 'sell'
    confidence: float
    expected_reward: float
```

### Enhanced Base Data Input

```python
@dataclass
class BaseDataInput:
    """Unified base data input for all models"""
    symbol: str
    timestamp: datetime
    ohlcv_data: Dict[str, OHLCVBar]  # Multi-timeframe OHLCV
    cob_data: Optional[Dict[str, float]] = None  # COB buckets for 1s timeframe
    technical_indicators: Dict[str, float] = field(default_factory=dict)
    pivot_points: List[PivotPoint] = field(default_factory=list)
    last_predictions: Dict[str, ModelOutput] = field(default_factory=dict)  # From all models
    market_microstructure: Dict[str, Any] = field(default_factory=dict)  # Order flow, etc.
```

### COB Data Structure

```python
@dataclass
class COBData:
    """Cumulative Order Book data for price buckets"""
    symbol: str
    timestamp: datetime
    current_price: float
    bucket_size: float  # $1 for ETH, $10 for BTC
    price_buckets: Dict[float, Dict[str, float]]  # price -> {bid_volume, ask_volume, etc.}
    bid_ask_imbalance: Dict[float, float]  # price -> imbalance ratio
    volume_weighted_prices: Dict[float, float]  # price -> VWAP within bucket
    order_flow_metrics: Dict[str, float]  # Various order flow indicators
```

### Data Collection Errors

- Implement retry mechanisms for API failures
- Use fallback data sources when primary sources are unavailable
- Log all errors with detailed information
- Notify users through the dashboard

### Model Errors

- Implement model validation before deployment
- Use fallback models when primary models fail
- Log all errors with detailed information
- Notify users through the dashboard

### Trading Errors

- Implement order validation before submission
- Use retry mechanisms for order failures
- Implement circuit breakers for extreme market conditions
- Log all errors with detailed information
- Notify users through the dashboard

## Testing Strategy

### Unit Testing

- Test individual components in isolation
- Use mock objects for dependencies
- Focus on edge cases and error handling

### Integration Testing

- Test interactions between components
- Use real data for testing
- Focus on data flow and error propagation

### System Testing

- Test the entire system end-to-end
- Use real data for testing
- Focus on performance and reliability

### Backtesting

- Test trading strategies on historical data
- Measure performance metrics (PnL, Sharpe ratio, etc.)
- Compare against benchmarks

### Live Testing

- Test the system in a live environment with small position sizes
- Monitor performance and stability
- Gradually increase position sizes as confidence grows

## Implementation Plan

The implementation will follow a phased approach:

1. **Phase 1: Data Provider**
   - Implement the enhanced data provider
   - Implement pivot point calculation
   - Implement technical indicator calculation
   - Implement data normalization

2. **Phase 2: CNN Model**
   - Implement the CNN model architecture
   - Implement the training pipeline
   - Implement the inference pipeline
   - Implement the pivot point prediction

3. **Phase 3: RL Model**
   - Implement the RL model architecture
   - Implement the training pipeline
   - Implement the inference pipeline
   - Implement the trading action generation

4. **Phase 4: Orchestrator**
   - Implement the orchestrator architecture
   - Implement the decision-making logic
   - Implement the MoE gateway
   - Implement the confidence-based filtering

5. **Phase 5: Trading Executor**
   - Implement the trading executor
   - Implement the brokerage API integrations
   - Implement the order management
   - Implement the error handling

6. **Phase 6: Risk Manager**
   - Implement the risk manager
   - Implement the stop-loss functionality
   - Implement the position sizing
   - Implement the risk metrics

7. **Phase 7: Dashboard**
   - Implement the dashboard UI
   - Implement the chart management
   - Implement the control panel
   - Implement the real-time updates

8. **Phase 8: Integration and Testing**
   - Integrate all components
   - Implement comprehensive testing
   - Fix bugs and optimize performance
   - Deploy to production

## Monitoring and Visualization

### TensorBoard Integration (Future Enhancement)

A comprehensive TensorBoard integration has been designed to provide detailed training visualization and monitoring capabilities:

#### Features
- **Training Metrics Visualization**: Real-time tracking of model losses, rewards, and performance metrics
- **Feature Distribution Analysis**: Histograms and statistics of input features to validate data quality
- **State Quality Monitoring**: Tracking of comprehensive state building (13,400 features) success rates
- **Reward Component Analysis**: Detailed breakdown of reward calculations including PnL, confidence, volatility, and order flow
- **Model Performance Comparison**: Side-by-side comparison of CNN, RL, and orchestrator performance

#### Implementation Status
- **Completed**: TensorBoardLogger utility class with comprehensive logging methods
- **Completed**: Integration points in enhanced_rl_training_integration.py
- **Completed**: Enhanced run_tensorboard.py with improved visualization options
- **Status**: Ready for deployment when system stability is achieved

#### Usage
```bash
# Start TensorBoard dashboard
python run_tensorboard.py

# Access at http://localhost:6006
# View training metrics, feature distributions, and model performance
```

#### Benefits
- Real-time validation of training process
- Early detection of training issues
- Feature importance analysis
- Model performance comparison
- Historical training progress tracking

**Note**: TensorBoard integration is currently deprioritized in favor of system stability and core model improvements. It will be activated once the core training system is stable and performing optimally.

## Conclusion

This design document outlines the architecture, components, data flow, and implementation details for the Multi-Modal Trading System. The system is designed to be modular, extensible, and robust, with a focus on performance, reliability, and user experience.

The implementation will follow a phased approach, with each phase building on the previous one. The system will be thoroughly tested at each phase to ensure that it meets the requirements and performs as expected.

The final system will provide traders with a powerful tool for analyzing market data, identifying trading opportunities, and executing trades with confidence.