gogo2/.kiro/specs/5.manual-trade-annotation-ui/requirements.md

Requirements Document

Introduction

This feature provides a web-based UI for manually annotating profitable buy/sell signals on historical market data to generate training test cases for machine learning models. The system allows traders to navigate through historical candlestick data across multiple timeframes, mark entry and exit points for trades, and use these annotations to train and evaluate trading models in real-time. The UI follows the design patterns of professional trading platforms like TradingView, with all HTML templates separated from Python code for maintainability.

Requirements

Requirement 1: Multi-Timeframe Chart Visualization

User Story: As a trader, I want to view candlestick charts across multiple timeframes simultaneously, so that I can analyze market structure at different scales before marking trade signals.

Acceptance Criteria

1. WHEN the UI loads THEN the system SHALL display candlestick charts for at least 4 configurable timeframes (e.g., 1m, 5m, 15m, 1h)
2. WHEN displaying charts THEN the system SHALL render OHLCV (Open, High, Low, Close, Volume) data as candlestick visualizations
3. WHEN charts are displayed THEN the system SHALL synchronize time navigation across all timeframe views
4. WHEN a user hovers over a candle THEN the system SHALL display detailed OHLCV information in a tooltip
5. IF historical data is available THEN the system SHALL load and cache data efficiently to support smooth navigation

Requirement 2: Time Navigation and Data Loading

User Story: As a trader, I want to navigate to any point in historical time and scroll through data smoothly, so that I can find specific market conditions to annotate.

Acceptance Criteria

1. WHEN the user enters a date/time THEN the system SHALL navigate to that specific point in the historical data
2. WHEN the user scrolls horizontally THEN the system SHALL load additional historical data dynamically without page refresh
3. WHEN navigating through time THEN the system SHALL maintain chart synchronization across all timeframes
4. WHEN data is loading THEN the system SHALL display a loading indicator
5. IF the user navigates beyond available data THEN the system SHALL display a clear message indicating data boundaries
6. WHEN the user uses keyboard shortcuts (arrow keys) THEN the system SHALL navigate forward/backward by configurable time increments

Requirement 3: Trade Position Marking

User Story: As a trader, I want to click on the chart to mark trade entry and exit points, so that I can create annotated training examples of profitable trades.

Acceptance Criteria

1. WHEN the user clicks on a candle THEN the system SHALL allow marking it as a trade entry point (buy signal)
2. WHEN a trade entry exists THEN the system SHALL allow clicking another candle to mark the exit point (sell signal)
3. WHEN a trade is marked THEN the system SHALL visually display the trade on the chart with entry/exit markers and a connecting line
4. WHEN a trade is complete THEN the system SHALL calculate and display the profit/loss percentage
5. WHEN the user clicks on an existing trade marker THEN the system SHALL allow editing or deleting the trade annotation
6. IF multiple trades overlap THEN the system SHALL display them with distinct visual indicators
7. WHEN a trade is created THEN the system SHALL store the trade annotation with timestamp, price, and timeframe information

Requirement 4: Test Case Generation

User Story: As a model trainer, I want the system to generate test cases from my manual annotations in the same format as realtime test cases, so that I can use them for model training.

Acceptance Criteria

1. WHEN a trade annotation is saved THEN the system SHALL generate a test case data structure identical to realtime test case format
2. WHEN generating test cases THEN the system SHALL include all relevant market state data at entry and exit points
3. WHEN generating test cases THEN the system SHALL capture data from all configured timeframes
4. WHEN test cases are generated THEN the system SHALL save them to a designated storage location accessible by training pipelines
5. IF a test case already exists for the same time period THEN the system SHALL allow overwriting or versioning
6. WHEN exporting test cases THEN the system SHALL support batch export of multiple annotations

Requirement 5: Model Integration and Training

User Story: As a model trainer, I want to load current models and run training sessions using generated test cases, so that I can improve model performance on manually validated scenarios.

Acceptance Criteria

1. WHEN the user requests model loading THEN the system SHALL load the current model checkpoints from the models directory
2. WHEN models are loaded THEN the system SHALL display model metadata (version, training date, performance metrics)
3. WHEN the user initiates training THEN the system SHALL run a training session using the generated test cases
4. WHEN training is running THEN the system SHALL display real-time training progress (loss, accuracy, epoch count)
5. WHEN training completes THEN the system SHALL save updated model checkpoints
6. IF training fails THEN the system SHALL display error messages and allow retry

Requirement 6: Realtime Inference Simulation

User Story: As a model evaluator, I want to simulate realtime inference on annotated data, so that I can measure model performance and validate that training improved decision-making.

Acceptance Criteria

1. WHEN the user requests inference simulation THEN the system SHALL replay the annotated time period with the loaded model
2. WHEN simulating inference THEN the system SHALL display model predictions at each timestep on the chart
3. WHEN simulation runs THEN the system SHALL compare model predictions against manual annotations
4. WHEN simulation completes THEN the system SHALL calculate and display performance metrics (accuracy, precision, recall, F1 score)
5. WHEN displaying predictions THEN the system SHALL use distinct visual markers to differentiate from manual annotations
6. IF the model makes incorrect predictions THEN the system SHALL highlight discrepancies for analysis
7. WHEN simulation is running THEN the system SHALL allow playback speed control (1x, 2x, 5x, 10x)

Requirement 7: Template-Based HTML Architecture

User Story: As a developer, I want all HTML to be in dedicated template files separate from Python code, so that the UI is maintainable and follows best practices.

Acceptance Criteria

1. WHEN implementing the UI THEN the system SHALL use a template engine (Jinja2 or similar) for HTML rendering
2. WHEN organizing files THEN the system SHALL store all HTML templates in a dedicated templates directory
3. WHEN creating templates THEN the system SHALL separate layout templates from component templates
4. WHEN Python code renders views THEN it SHALL pass data to templates without embedding HTML strings
5. IF templates share common elements THEN the system SHALL use template inheritance or includes
6. WHEN styling the UI THEN CSS SHALL be in separate stylesheet files, not inline styles
7. WHEN adding interactivity THEN JavaScript SHALL be in separate files, not inline scripts

Requirement 8: Data Persistence and Session Management

User Story: As a trader, I want my annotations and UI state to be saved automatically, so that I can resume work across sessions without losing progress.

Acceptance Criteria

1. WHEN a trade annotation is created THEN the system SHALL automatically save it to persistent storage
2. WHEN the user closes the browser THEN the system SHALL preserve all annotations and UI state
3. WHEN the user returns to the UI THEN the system SHALL restore the previous session state (timeframe, position, annotations)
4. WHEN annotations are modified THEN the system SHALL maintain version history for audit purposes
5. IF the system crashes THEN annotations SHALL be recoverable from the last auto-save point
6. WHEN exporting data THEN the system SHALL support exporting annotations in JSON or CSV format

Requirement 9: Trading Platform UI Features

User Story: As a trader familiar with TradingView, I want the UI to have similar professional features, so that I can work efficiently with familiar patterns.

Acceptance Criteria

1. WHEN using the chart THEN the system SHALL support zoom in/out functionality (mouse wheel or pinch gestures)
2. WHEN viewing charts THEN the system SHALL display a crosshair cursor that shows price and time coordinates
3. WHEN the user draws on charts THEN the system SHALL support basic drawing tools (horizontal lines, trend lines)
4. WHEN displaying data THEN the system SHALL show volume bars below price charts
5. WHEN the UI is displayed THEN it SHALL be responsive and work on different screen sizes
6. WHEN interacting with charts THEN the system SHALL provide smooth animations and transitions
7. IF the user has multiple monitors THEN the system SHALL support full-screen mode

Requirement 10: Configuration and Symbol Management

User Story: As a trader, I want to configure which trading pairs and timeframes to display, so that I can focus on specific markets I'm analyzing.

Acceptance Criteria

1. WHEN the UI loads THEN the system SHALL allow selecting trading pairs from available data sources
2. WHEN configuring timeframes THEN the system SHALL allow enabling/disabling specific timeframe charts
3. WHEN settings are changed THEN the system SHALL persist configuration preferences per user
4. WHEN switching symbols THEN the system SHALL load the appropriate historical data and preserve annotations per symbol
5. IF data is unavailable for a symbol/timeframe combination THEN the system SHALL display a clear error message
6. WHEN configuring data sources THEN the system SHALL support multiple exchange data sources (matching existing data providers)