# Design Document

## Overview

The Manual Trade Annotation UI is a web-based application that enables traders to manually mark profitable buy/sell signals on historical market data for generating training test cases. The system integrates with the existing trading infrastructure, leveraging the DataProvider for historical data access, model loading capabilities from the orchestrator, and training systems to validate annotations through real-time inference simulation.

The UI follows a template-based architecture using Flask/Dash with Jinja2 templates, separating HTML, CSS, and JavaScript from Python code. It provides a TradingView-like experience with multi-timeframe charts, time navigation, and interactive trade marking capabilities.

## Architecture

### High-Level Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                    Browser (Client)                          │
│  ┌────────────────────────────────────────────────────────┐ │
│  │  HTML Templates (Jinja2)                               │ │
│  │  - layout.html (base template)                         │ │
│  │  - annotation_dashboard.html (main UI)                 │ │
│  │  - chart_component.html (chart widget)                 │ │
│  │  - controls_panel.html (navigation/controls)           │ │
│  └────────────────────────────────────────────────────────┘ │
│  ┌────────────────────────────────────────────────────────┐ │
│  │  JavaScript (static/js/)                               │ │
│  │  - chart_manager.js (Plotly chart handling)            │ │
│  │  - annotation_manager.js (trade marking logic)         │ │
│  │  - time_navigator.js (time navigation)                 │ │
│  │  - training_controller.js (training/inference UI)      │ │
│  └────────────────────────────────────────────────────────┘ │
│  ┌────────────────────────────────────────────────────────┐ │
│  │  CSS (static/css/)                                     │ │
│  │  - annotation_ui.css (main styles)                     │ │
│  │  - dark_theme.css (dark mode theme)                    │ │
│  └────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
                            │
                            │ HTTP/WebSocket
                            ▼
┌─────────────────────────────────────────────────────────────┐
│              Flask/Dash Application Server                   │
│  ┌────────────────────────────────────────────────────────┐ │
│  │  web/annotation_dashboard.py                           │ │
│  │  - Flask routes for page rendering                     │ │
│  │  - Dash callbacks for interactivity                    │ │
│  │  - WebSocket handlers for real-time updates            │ │
│  └────────────────────────────────────────────────────────┘ │
│  ┌────────────────────────────────────────────────────────┐ │
│  │  core/annotation_manager.py                            │ │
│  │  - Trade annotation storage/retrieval                  │ │
│  │  - Test case generation                                │ │
│  │  - Annotation validation                               │ │
│  └────────────────────────────────────────────────────────┘ │
│  ┌────────────────────────────────────────────────────────┐ │
│  │  core/training_simulator.py                            │ │
│  │  - Model loading/management                            │ │
│  │  - Training execution                                  │ │
│  │  - Inference simulation                                │ │
│  └────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
                            │
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│              Existing Infrastructure                         │
│  ┌────────────────────────────────────────────────────────┐ │
│  │  core/data_provider.py                                 │ │
│  │  - Historical data fetching                            │ │
│  │  - Multi-timeframe data access                         │ │
│  │  - Caching layer                                       │ │
│  └────────────────────────────────────────────────────────┘ │
│  ┌────────────────────────────────────────────────────────┐ │
│  │  core/orchestrator.py                                  │ │
│  │  - Model registry access                               │ │
│  │  - Model loading                                       │ │
│  └────────────────────────────────────────────────────────┘ │
│  ┌────────────────────────────────────────────────────────┐ │
│  │  NN/models/* (CNN, DQN, Transformer)                   │ │
│  │  - Model implementations                               │ │
│  │  - Training interfaces                                 │ │
│  └────────────────────────────────────────────────────────┘ │
│  ┌────────────────────────────────────────────────────────┐ │
│  │  data/annotations/ (Storage)                           │ │
│  │  - annotation_db.json (annotation metadata)            │ │
│  │  - test_cases/ (generated test cases)                  │ │
│  │  - training_results/ (training metrics)                │ │
│  └────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```

### Component Interaction Flow

1. **User Interaction**: User navigates to annotation UI, selects symbol/timeframe
2. **Data Loading**: Server fetches historical data from DataProvider
3. **Chart Rendering**: Plotly charts rendered in browser with candlestick data
4. **Trade Marking**: User clicks to mark entry/exit points
5. **Annotation Storage**: Annotations saved to database with full market context
6. **Test Case Generation**: System generates test cases in realtime format
7. **Model Training**: User triggers training with generated test cases
8. **Inference Simulation**: System replays annotated period with model predictions
9. **Performance Metrics**: Display accuracy, precision, recall against annotations

## Components and Interfaces

### 1. Web Application Layer

#### AnnotationDashboard (web/annotation_dashboard.py)

Main Flask/Dash application that serves the UI and handles user interactions.

```python
class AnnotationDashboard:
    """Main annotation dashboard application"""
    
    def __init__(self, data_provider: DataProvider, orchestrator: TradingOrchestrator):
        self.app = Dash(__name__)
        self.data_provider = data_provider
        self.orchestrator = orchestrator
        self.annotation_manager = AnnotationManager()
        self.training_simulator = TrainingSimulator(orchestrator)
        
    def setup_layout(self) -> html.Div:
        """Setup dashboard layout using templates"""
        
    def setup_callbacks(self):
        """Setup Dash callbacks for interactivity"""
        
    @app.callback(...)
    def update_charts(symbol, timeframe, start_time, end_time):
        """Update charts based on navigation"""
        
    @app.callback(...)
    def handle_chart_click(click_data, current_annotations):
        """Handle chart clicks for trade marking"""
        
    @app.callback(...)
    def generate_test_case(annotation_id):
        """Generate test case from annotation"""
        
    @app.callback(...)
    def run_training(test_case_ids, model_name):
        """Run training with selected test cases"""
        
    @app.callback(...)
    def simulate_inference(annotation_id, model_name):
        """Simulate inference on annotated period"""
```

**Key Methods:**
- `setup_layout()`: Creates UI layout using Jinja2 templates
- `setup_callbacks()`: Registers Dash callbacks for interactivity
- `load_historical_data()`: Fetches data from DataProvider
- `render_charts()`: Generates Plotly chart figures
- `handle_websocket_updates()`: Manages real-time updates

#### Template Structure (web/templates/)

```
templates/
├── base_layout.html          # Base template with common elements
├── annotation_dashboard.html # Main dashboard page
├── components/
│   ├── chart_panel.html      # Multi-timeframe chart display
│   ├── control_panel.html    # Navigation and controls
│   ├── annotation_list.html  # List of saved annotations
│   ├── training_panel.html   # Training controls and metrics
│   └── inference_panel.html  # Inference simulation display
```

**Template Variables:**
- `symbols`: Available trading pairs
- `timeframes`: Available timeframes
- `annotations`: List of saved annotations
- `chart_data`: Chart configuration and data
- `model_list`: Available models for training
- `training_status`: Current training status
- `inference_results`: Inference simulation results

### 2. Annotation Management Layer

#### AnnotationManager (core/annotation_manager.py)

Manages trade annotations, storage, and test case generation.

```python
@dataclass
class TradeAnnotation:
    """Represents a manually marked trade"""
    annotation_id: str
    symbol: str
    timeframe: str
    entry_timestamp: datetime
    entry_price: float
    exit_timestamp: datetime
    exit_price: float
    direction: str  # 'LONG' or 'SHORT'
    profit_loss_pct: float
    notes: str
    created_at: datetime
    market_context: Dict[str, Any]  # Full market state at entry/exit
    
class AnnotationManager:
    """Manages trade annotations and test case generation"""
    
    def __init__(self, storage_path: str = "data/annotations"):
        self.storage_path = Path(storage_path)
        self.annotations_db = self._load_annotations()
        
    def create_annotation(self, entry_point: Dict, exit_point: Dict, 
                         symbol: str, timeframe: str) -> TradeAnnotation:
        """Create new trade annotation"""
        
    def save_annotation(self, annotation: TradeAnnotation):
        """Save annotation to storage"""
        
    def get_annotations(self, symbol: str = None, 
                       timeframe: str = None) -> List[TradeAnnotation]:
        """Retrieve annotations with optional filtering"""
        
    def delete_annotation(self, annotation_id: str):
        """Delete annotation"""
        
    def generate_test_case(self, annotation: TradeAnnotation) -> Dict:
        """Generate test case from annotation in realtime format"""
        
    def export_test_cases(self, annotation_ids: List[str], 
                         output_path: str):
        """Export multiple test cases"""
```

**Key Responsibilities:**
- Store/retrieve trade annotations
- Validate annotation data
- Generate test cases in realtime format
- Manage annotation metadata
- Handle annotation versioning

#### Test Case Format

Test cases generated from annotations match the realtime test case format:

```python
{
    "test_case_id": "annotation_<annotation_id>",
    "symbol": "ETH/USDT",
    "timestamp": "2024-01-15T10:30:00Z",
    "action": "BUY",  # or "SELL"
    "market_state": {
        # Full BaseDataInput structure
        "ohlcv_1s": [...],  # Last 100 candles
        "ohlcv_1m": [...],  # Last 100 candles
        "ohlcv_1h": [...],  # Last 100 candles
        "ohlcv_1d": [...],  # Last 100 candles
        "cob_data": {...},  # Order book snapshot
        "technical_indicators": {...},
        "pivot_points": [...]
    },
    "expected_outcome": {
        "direction": "LONG",
        "profit_loss_pct": 2.5,
        "holding_period_seconds": 300,
        "exit_price": 2450.50
    },
    "annotation_metadata": {
        "annotator": "manual",
        "confidence": 1.0,  # Manual annotations are 100% confident
        "notes": "Clear breakout pattern"
    }
}
```

### 3. Training Simulation Layer

#### TrainingSimulator (core/training_simulator.py)

Handles model loading, training execution, and inference simulation.

```python
class TrainingSimulator:
    """Simulates training and inference on annotated data"""
    
    def __init__(self, orchestrator: TradingOrchestrator):
        self.orchestrator = orchestrator
        self.data_provider = orchestrator.data_provider
        self.model_cache = {}
        
    def load_model(self, model_name: str) -> ModelInterface:
        """Load model from checkpoint"""
        
    def train_on_test_cases(self, test_cases: List[Dict], 
                           model_name: str) -> TrainingResults:
        """Train model on generated test cases"""
        
    def simulate_inference(self, annotation: TradeAnnotation, 
                          model_name: str) -> InferenceResults:
        """Simulate inference on annotated time period"""
        
    def calculate_performance_metrics(self, predictions: List[Dict], 
                                     annotations: List[TradeAnnotation]) -> Dict:
        """Calculate accuracy, precision, recall, F1"""
        
    def get_training_progress(self, training_id: str) -> Dict:
        """Get real-time training progress"""

@dataclass
class TrainingResults:
    """Results from training session"""
    training_id: str
    model_name: str
    test_cases_used: int
    epochs_completed: int
    final_loss: float
    training_duration_seconds: float
    checkpoint_path: str
    metrics: Dict[str, float]
    
@dataclass
class InferenceResults:
    """Results from inference simulation"""
    annotation_id: str
    model_name: str
    predictions: List[Dict]  # Timestamped predictions
    accuracy: float
    precision: float
    recall: float
    f1_score: float
    confusion_matrix: Dict
    prediction_timeline: List[Dict]  # For visualization
```

**Key Responsibilities:**
- Load models from checkpoints
- Execute training sessions
- Simulate real-time inference
- Calculate performance metrics
- Track training progress
- Generate performance reports

### 4. Chart Management (Client-Side)

#### ChartManager (static/js/chart_manager.js)

Manages Plotly charts for multi-timeframe visualization.

```javascript
class ChartManager {
    constructor(containerId, timeframes) {
        this.containerId = containerId;
        this.timeframes = timeframes;
        this.charts = {};
        this.syncedCursor = null;
    }
    
    initializeCharts(data) {
        // Create Plotly charts for each timeframe
    }
    
    updateCharts(newData) {
        // Update chart data without full re-render
    }
    
    syncTimeNavigation(timestamp) {
        // Synchronize all charts to same time point
    }
    
    addAnnotation(annotation) {
        // Add trade annotation markers to charts
    }
    
    removeAnnotation(annotationId) {
        // Remove annotation markers
    }
    
    highlightPrediction(prediction) {
        // Highlight model predictions on chart
    }
    
    enableCrosshair() {
        // Enable crosshair cursor with price/time display
    }
    
    handleZoom(zoomLevel) {
        // Handle zoom in/out
    }
}
```

#### AnnotationManager (static/js/annotation_manager.js)

Manages trade marking interactions.

```javascript
class AnnotationManager {
    constructor(chartManager) {
        this.chartManager = chartManager;
        this.pendingAnnotation = null;
        this.annotations = [];
    }
    
    handleChartClick(clickData) {
        // Handle click to mark entry/exit
    }
    
    createAnnotation(entryPoint, exitPoint) {
        // Create annotation object
    }
    
    saveAnnotation(annotation) {
        // Send annotation to server
    }
    
    deleteAnnotation(annotationId) {
        // Delete annotation
    }
    
    calculateProfitLoss(entry, exit, direction) {
        // Calculate P&L percentage
    }
    
    validateAnnotation(annotation) {
        // Validate annotation data
    }
}
```

#### TimeNavigator (static/js/time_navigator.js)

Handles time navigation and data loading.

```javascript
class TimeNavigator {
    constructor(chartManager, dataLoader) {
        this.chartManager = chartManager;
        this.dataLoader = dataLoader;
        this.currentTime = null;
        this.timeRange = null;
    }
    
    navigateToTime(timestamp) {
        // Navigate to specific time
    }
    
    scrollForward(increment) {
        // Scroll forward in time
    }
    
    scrollBackward(increment) {
        // Scroll backward in time
    }
    
    loadDataRange(startTime, endTime) {
        // Load data for time range
    }
    
    setupKeyboardShortcuts() {
        // Setup arrow key navigation
    }
}
```

## Data Models

### Annotation Storage Schema

```json
{
  "annotations": [
    {
      "annotation_id": "uuid-string",
      "symbol": "ETH/USDT",
      "timeframe": "1m",
      "entry": {
        "timestamp": "2024-01-15T10:30:00Z",
        "price": 2400.50,
        "candle_index": 1234
      },
      "exit": {
        "timestamp": "2024-01-15T10:35:00Z",
        "price": 2450.75,
        "candle_index": 1239
      },
      "direction": "LONG",
      "profit_loss_pct": 2.09,
      "notes": "Clear breakout pattern with volume confirmation",
      "created_at": "2024-01-15T11:00:00Z",
      "market_context": {
        "entry_state": { /* Full BaseDataInput */ },
        "exit_state": { /* Full BaseDataInput */ }
      },
      "tags": ["breakout", "high-volume"],
      "version": 1
    }
  ],
  "metadata": {
    "total_annotations": 150,
    "symbols": ["ETH/USDT", "BTC/USDT"],
    "timeframes": ["1s", "1m", "1h"],
    "last_updated": "2024-01-15T11:00:00Z"
  }
}
```

### Training Session Schema

```json
{
  "training_sessions": [
    {
      "training_id": "uuid-string",
      "model_name": "StandardizedCNN",
      "start_time": "2024-01-15T11:00:00Z",
      "end_time": "2024-01-15T11:15:00Z",
      "test_cases_used": ["annotation_1", "annotation_2"],
      "hyperparameters": {
        "learning_rate": 0.001,
        "batch_size": 32,
        "epochs": 50
      },
      "results": {
        "final_loss": 0.045,
        "best_loss": 0.042,
        "epochs_completed": 50,
        "checkpoint_path": "models/checkpoints/cnn_annotation_training_20240115.pt"
      },
      "metrics": {
        "accuracy": 0.85,
        "precision": 0.82,
        "recall": 0.88,
        "f1_score": 0.85
      }
    }
  ]
}
```

## Error Handling

### Client-Side Error Handling

1. **Network Errors**: Retry with exponential backoff
2. **Invalid Annotations**: Validate before sending to server
3. **Chart Rendering Errors**: Fallback to simplified chart
4. **WebSocket Disconnection**: Auto-reconnect with state recovery

### Server-Side Error Handling

1. **Data Loading Errors**: Return cached data or error message
2. **Model Loading Errors**: Provide clear error message with troubleshooting
3. **Training Errors**: Capture and display error logs
4. **Storage Errors**: Implement transaction rollback

### Error Response Format

```json
{
  "success": false,
  "error": {
    "code": "MODEL_LOAD_ERROR",
    "message": "Failed to load model checkpoint",
    "details": "Checkpoint file not found: models/checkpoints/cnn_best.pt",
    "timestamp": "2024-01-15T11:00:00Z",
    "suggestions": [
      "Check if checkpoint file exists",
      "Verify model path in configuration",
      "Try loading a different checkpoint"
    ]
  }
}
```

## Testing Strategy

### Unit Tests

1. **AnnotationManager Tests**
   - Test annotation creation/storage/retrieval
   - Test test case generation
   - Test validation logic

2. **TrainingSimulator Tests**
   - Test model loading
   - Test training execution
   - Test inference simulation
   - Test metrics calculation

3. **Data Provider Integration Tests**
   - Test historical data fetching
   - Test multi-timeframe data access
   - Test caching behavior

### Integration Tests

1. **End-to-End Annotation Flow**
   - Create annotation → Generate test case → Train model → Simulate inference

2. **Multi-Timeframe Synchronization**
   - Verify all timeframes stay synchronized during navigation

3. **Model Training Integration**
   - Verify training with generated test cases
   - Verify checkpoint saving/loading

### UI Tests

1. **Chart Interaction Tests**
   - Test chart rendering
   - Test click handling for trade marking
   - Test zoom/pan functionality

2. **Navigation Tests**
   - Test time navigation
   - Test keyboard shortcuts
   - Test data loading on scroll

3. **Training UI Tests**
   - Test training progress display
   - Test inference simulation visualization
   - Test performance metrics display

## Performance Considerations

### Data Loading Optimization

1. **Lazy Loading**: Load data only when needed
2. **Caching**: Cache frequently accessed data
3. **Pagination**: Load data in chunks for large time ranges
4. **Compression**: Compress data for network transfer

### Chart Rendering Optimization

1. **Downsampling**: Reduce data points for distant time ranges
2. **Virtual Scrolling**: Render only visible candles
3. **WebGL Rendering**: Use Plotly WebGL for large datasets
4. **Debouncing**: Debounce zoom/pan events

### Training Performance

1. **Batch Processing**: Process multiple test cases in batches
2. **GPU Utilization**: Leverage GPU for training when available
3. **Checkpoint Frequency**: Save checkpoints periodically
4. **Progress Streaming**: Stream training progress to UI

### Memory Management

1. **Data Cleanup**: Clear old data from memory
2. **Model Unloading**: Unload unused models
3. **Chart Cleanup**: Destroy unused chart instances
4. **WebSocket Buffer Limits**: Limit WebSocket message buffer size

## Security Considerations

1. **Input Validation**: Validate all user inputs
2. **SQL Injection Prevention**: Use parameterized queries
3. **XSS Prevention**: Sanitize user-provided notes/tags
4. **CSRF Protection**: Implement CSRF tokens
5. **Rate Limiting**: Limit API requests per user
6. **Authentication**: Add user authentication if needed
7. **Authorization**: Control access to training/model operations

## Deployment Considerations

1. **Configuration**: Externalize configuration (ports, paths, etc.)
2. **Logging**: Comprehensive logging for debugging
3. **Monitoring**: Monitor training sessions and system resources
4. **Backup**: Regular backup of annotations and training results
5. **Scalability**: Design for multiple concurrent users
6. **Documentation**: Provide user guide and API documentation