# Product Requirements Document: Crypto Trading Bot Dashboard

## Introduction/Overview

Create a simple control dashboard for managing and monitoring multiple cryptocurrency trading bots simultaneously. The system will allow testing different strategies in parallel using real OKX market data and virtual trading simulation. The focus is on rapid implementation to enable strategy testing within days rather than weeks.

**Core Problem**: Currently, testing multiple trading strategies requires manual coordination and lacks real-time monitoring capabilities. There's no unified way to compare strategy performance or manage multiple bots running simultaneously.

## Goals

1. **Enable Parallel Strategy Testing**: Run up to 5 different trading bots simultaneously with different strategies
2. **Real-time Monitoring**: Visualize bot performance, trading decisions, and market data in real-time
3. **Quick Strategy Validation**: Reduce the time from strategy implementation to performance assessment
4. **Historical Analysis**: Enable backtesting with previously collected market data
5. **Operational Control**: Simple start/stop functionality for individual bots

## User Stories

1. **As a strategy developer**, I want to start multiple bots with different strategies so that I can compare their performance over the same time period.

2. **As a trader**, I want to see real-time price charts and bot decisions so that I can understand how my strategies are performing.

3. **As an analyst**, I want to view historical performance metrics so that I can evaluate strategy effectiveness over different market conditions.

4. **As a system operator**, I want to stop underperforming bots so that I can prevent further virtual losses.

5. **As a researcher**, I want to run backtests on historical data so that I can validate strategies before live testing.

## Functional Requirements

### Core Bot Management
1. **Bot Lifecycle Control**: System must allow starting and stopping individual bots via web interface
2. **Multi-Bot Support**: System must support running up to 5 bots simultaneously
3. **Bot Configuration**: System must read bot configurations from JSON/YAML files in a configs directory
4. **Status Monitoring**: System must display current status (running/stopped) for each configured bot

### Data Management
5. **Market Data Integration**: System must connect to existing OKX data feed and display real-time price information
6. **Trading Decision Storage**: System must record all bot trading decisions (buy/sell signals, amounts, timestamps) to database
7. **Performance Tracking**: System must calculate and store key metrics (balance, profit/loss, number of trades) for each bot
8. **Data Persistence**: System must use SQLite for simplicity with separate tables for market data and bot decisions

### User Interface
9. **Dashboard Layout**: System must provide a single-page dashboard showing all bot information
10. **Price Visualization**: System must display candlestick charts with bot buy/sell markers overlaid
11. **Bot Switching**: System must allow switching chart view between different active bots
12. **Performance Metrics**: System must show current balance, total profit/loss, and trade count for each bot and trade time
13. **Real-time Updates**: System must refresh data every 2 seconds minimum

### Backtesting
14. **Historical Mode**: System must allow running bots against historical market data
15. **Time Range Selection**: System must provide date range picker for backtest periods
16. **Accelerated Testing**: System must support running backtests faster than real-time

## Non-Goals (Out of Scope)

- **Multi-exchange Support**: Only OKX integration for MVP
- **Real Money Trading**: Virtual trading simulation only
- **Advanced UI/UX**: Basic functional interface, not polished design
- **User Authentication**: Single-user system for MVP
- **Strategy Editor**: Strategy creation/editing via code only, not UI
- **Advanced Analytics**: Complex statistical analysis beyond basic P&L
- **Mobile Interface**: Desktop web interface only
- **High-frequency Trading**: Strategies with sub-second requirements not supported

## Technical Considerations

### Technology Stack
- **Backend**: Python with existing OKX, strategy, and trader modules
- **Frontend**: Plotly Dash for rapid development and Python integration
- **Database**: PostgreSQL, SQLAlchemy
- **Communication**: Direct database polling (no WebSockets for MVP)

### Architecture Simplicity
- **Monolithic Design**: Single Python application with all components
- **File-based Configuration**: JSON files for bot settings
- **Polling Updates**: 2-second refresh cycle acceptable for MVP
- **Process Management**: Simple threading or multiprocessing for bot execution

### Integration Requirements
- **Existing Module Refactoring**: May need to modify current strategy and trader modules for unified signal processing
- **Database Schema**: Design simple schema for bot decisions and performance metrics
- **Error Handling**: Basic error logging and bot restart capabilities

## Success Metrics

1. **Functionality**: Successfully run 3+ bots simultaneously for 24+ hours without crashes
2. **Data Completeness**: Capture 100% of trading decisions and market data during bot operation
3. **Performance Visibility**: Display real-time bot performance with <5 second update latency
4. **Backtesting Capability**: Run historical tests covering 1+ weeks of data in <10 minutes
5. **Operational Control**: Start/stop bots with <10 second response time

## Design Considerations

### Dashboard Layout
```
+------------------+-------------------+
|   Bot Controls   |   Active Charts   |
| [Bot1] [Start]   |                   |
| [Bot2] [Stop]    |   Price/Strategy  |
| [Bot3] [Start]   |      Chart        |
+------------------+-------------------+
|           Performance Metrics        |
| Bot1: +$50  Bot2: -$20  Bot3: +$35  |
+--------------------------------------+
```

### Configuration Example
```json
{
  "bot_id": "ema_crossover_01",
  "strategy": "EMA_Crossover",
  "parameters": {
    "fast_period": 12,
    "slow_period": 26,
    "symbol": "BTC-USDT"
  },
  "virtual_balance": 10000
}
```

## Implementation Phases

### Phase 1 (Week 1-2): Core Infrastructure
- Set up basic Dash application
- Integrate existing OKX data feed
- Create bot manager for start/stop functionality
- Basic database schema for trading decisions

### Phase 2 (Week 3): Visualization
- Implement price charts with Plotly
- Add bot decision overlays
- Create performance metrics dashboard
- Bot switching functionality

### Phase 3 (Week 4): Testing & Refinement
- Add backtesting capability
- Implement error handling and logging
- Performance optimization
- User acceptance testing

## Open Questions

1. **Strategy Module Integration**: What modifications are needed to current strategy modules for unified signal processing?
2. **Database Migration**: Start with PostgreSQL
3. **Bot Resource Management**: How should we handle memory/CPU limits for individual bots?
4. **Configuration Management**: Bot can have hot reloading (we can save current active, paused bots so on start it restore last state.)
5. **Error Recovery**: On bot crash system should restart it if it is active.

## Acceptance Criteria

- [ ] Start 5 different bots simultaneously via web interface
- [ ] View real-time price charts with buy/sell decision markers
- [ ] Switch between different bot views in the dashboard
- [ ] See current virtual balance and P&L for each bot
- [ ] Stop/start individual bots without affecting others
- [ ] Run backtest on 1 week of historical data
- [ ] System operates continuously for 48+ hours without manual intervention
- [ ] All trading decisions logged to database with timestamps