TCPDashboard/docs/modules/charts/README.md

# Modular Chart Layers System

The Modular Chart Layers System is a flexible, strategy-driven chart system that supports technical indicator overlays, subplot management, and future bot signal integration. This system replaces basic chart functionality with a modular architecture that adapts to different trading strategies and their specific indicator requirements.

## Table of Contents

- [Overview](#overview)
- [Architecture](#architecture)
- [Quick Start](#quick-start)
- [Components](#components)
- [User Indicator Management](#user-indicator-management)
- [Configuration System](#configuration-system)
- [Example Strategies](#example-strategies)
- [Validation System](#validation-system)
- [API Reference](#api-reference)
- [Examples](#examples)
- [Best Practices](#best-practices)

## Overview

### Key Features

- **Modular Architecture**: Chart layers can be independently tested and composed
- **User Indicator Management**: Create, edit, and manage custom indicators with JSON persistence
- **Strategy-Driven Configuration**: JSON-based configurations for different trading strategies
- **Comprehensive Validation**: 10+ validation rules with detailed error reporting
- **Example Strategies**: 5 real-world trading strategy templates
- **Indicator Support**: 26+ professionally configured indicator presets
- **Extensible Design**: Easy to add new indicators, strategies, and chart types

### Supported Indicators

**Trend Indicators:**
- Simple Moving Average (SMA) - Multiple periods
- Exponential Moving Average (EMA) - Multiple periods
- Bollinger Bands - Various configurations

**Momentum Indicators:**
- Relative Strength Index (RSI) - Multiple periods
- MACD - Various speed configurations

**Volume Indicators:**
- Volume analysis and confirmation

## Architecture

```
components/charts/
├── indicator_manager.py      # User indicator CRUD operations
├── indicator_defaults.py     # Default indicator templates
├── config/                   # Configuration management
│   ├── indicator_defs.py     # Indicator schemas and validation
│   ├── defaults.py           # Default configurations and presets
│   ├── strategy_charts.py    # Strategy-specific configurations
│   ├── validation.py         # Validation system
│   ├── example_strategies.py # Real-world strategy examples
│   └── __init__.py          # Package exports
├── layers/                   # Chart layer implementation
│   ├── base.py              # Base layer system
│   ├── indicators.py        # Indicator overlays
│   ├── subplots.py          # Subplot management
│   └── signals.py           # Signal overlays (future)
├── builder.py               # Main chart builder
└── utils.py                 # Chart utilities

dashboard/                    # Modular dashboard integration
├── layouts/market_data.py    # Chart layout with controls
├── callbacks/charts.py      # Chart update callbacks
├── components/
│   ├── chart_controls.py    # Reusable chart configuration panel
│   └── indicator_modal.py   # Indicator management UI

config/indicators/
└── user_indicators/         # User-created indicators (JSON files)
    ├── sma_abc123.json
    ├── ema_def456.json
    └── ...
```

## Dashboard Integration

The chart system is fully integrated with the modular dashboard structure:

### Modular Components

- **`dashboard/layouts/market_data.py`** - Chart layout with strategy selection and indicator controls
- **`dashboard/callbacks/charts.py`** - Chart update callbacks with strategy handling
- **`dashboard/components/chart_controls.py`** - Reusable chart configuration panel
- **`dashboard/components/indicator_modal.py`** - Complete indicator management interface

### Key Features

- **Strategy Dropdown**: Auto-loads predefined indicator combinations
- **Real-time Updates**: Charts update immediately with indicator changes
- **Modular Architecture**: Each component under 300 lines for maintainability
- **Separated Concerns**: Layouts, callbacks, and components in dedicated modules

### Usage in Dashboard

```python
# From dashboard/layouts/market_data.py
from components.charts.config import get_available_strategy_names
from components.charts.indicator_manager import get_indicator_manager

# Get available strategies for dropdown
strategy_names = get_available_strategy_names()
strategy_options = [{'label': name.replace('_', ' ').title(), 'value': name} 
                   for name in strategy_names]

# Get user indicators for checklists
indicator_manager = get_indicator_manager()
overlay_indicators = indicator_manager.get_indicators_by_type('overlay')
subplot_indicators = indicator_manager.get_indicators_by_type('subplot')
```

For complete dashboard documentation, see [Dashboard Modular Structure (`../dashboard-modular-structure.md`)](../dashboard-modular-structure.md).

## User Indicator Management

The system includes a comprehensive user indicator management system that allows creating, editing, and managing custom technical indicators.

### Features

- **Interactive UI**: Modal dialog for creating and editing indicators
- **Real-time Updates**: Charts update immediately when indicators are toggled
- **JSON Persistence**: Each indicator saved as individual JSON file
- **Full CRUD Operations**: Create, Read, Update, Delete functionality
- **Type Validation**: Parameter validation based on indicator type
- **Custom Styling**: Color, line width, and appearance customization

### Quick Access

- **📊 [Complete Indicator Documentation (`indicators.md`)](./indicators.md)** - Comprehensive guide to the indicator system
- **⚡ [Quick Guide: Adding New Indicators (`adding-new-indicators.md`)](./adding-new-indicators.md)** - Step-by-step checklist for developers

### Current User Indicators

| Indicator | Type | Parameters | Display |
|-----------|------|------------|---------|
| Simple Moving Average (SMA) | `sma` | period (1-200) | Overlay |
| Exponential Moving Average (EMA) | `ema` | period (1-200) | Overlay |
| Bollinger Bands | `bollinger_bands` | period (5-100), std_dev (0.5-5.0) | Overlay |
| Relative Strength Index (RSI) | `rsi` | period (2-50) | Subplot |
| MACD | `macd` | fast_period, slow_period, signal_period | Subplot |

### Usage Example

```python
# Get indicator manager
from components.charts.indicator_manager import get_indicator_manager
manager = get_indicator_manager()

# Create new indicator
indicator = manager.create_indicator(
    name="My SMA 50",
    indicator_type="sma",
    parameters={"period": 50},
    description="50-period Simple Moving Average",
    color="#ff0000"
)

# Load and update
loaded = manager.load_indicator("sma_abc123")
success = manager.update_indicator("sma_abc123", name="Updated SMA")

# Get indicators by type
overlay_indicators = manager.get_indicators_by_type("overlay")
subplot_indicators = manager.get_indicators_by_type("subplot")
```

## Quick Start

### Basic Usage

```python
from components.charts.config import (
    create_ema_crossover_strategy,
    get_strategy_config,
    validate_configuration
)

# Get a pre-built strategy
strategy = create_ema_crossover_strategy()
config = strategy.config

# Validate the configuration
report = validate_configuration(config)
if report.is_valid:
    print("Configuration is valid!")
else:
    print(f"Errors: {[str(e) for e in report.errors]}")

# Use with dashboard
# chart = create_chart(config, market_data)
```

### Custom Strategy Creation

```python
from components.charts.config import (
    StrategyChartConfig,
    SubplotConfig,
    ChartStyle,
    TradingStrategy,
    SubplotType
)

# Create custom strategy
config = StrategyChartConfig(
    strategy_name="My Custom Strategy",
    strategy_type=TradingStrategy.DAY_TRADING,
    description="Custom day trading strategy",
    timeframes=["15m", "1h"],
    overlay_indicators=["ema_12", "ema_26", "bb_20_20"],
    subplot_configs=[
        SubplotConfig(
            subplot_type=SubplotType.RSI,
            height_ratio=0.2,
            indicators=["rsi_14"]
        )
    ]
)

# Validate and use
is_valid, errors = config.validate()
```

## Components

### 1. Configuration System

The configuration system provides schema validation, default presets, and strategy management.

**Key Files:**
- `indicator_defs.py` - Core schemas and validation
- `defaults.py` - 26+ indicator presets organized by category
- `strategy_charts.py` - Complete strategy configurations

**Features:**
- Type-safe indicator definitions
- Parameter validation with ranges
- Category-based organization (trend, momentum, volatility)
- Strategy-specific recommendations

### 2. Validation System

Comprehensive validation with 10 validation rules:

1. **Required Fields** - Essential configuration validation
2. **Height Ratios** - Chart layout validation
3. **Indicator Existence** - Indicator availability check
4. **Timeframe Format** - Valid timeframe patterns
5. **Chart Style** - Color and styling validation
6. **Subplot Config** - Subplot compatibility check
7. **Strategy Consistency** - Strategy-timeframe alignment
8. **Performance Impact** - Resource usage warnings
9. **Indicator Conflicts** - Redundancy detection
10. **Resource Usage** - Memory and rendering estimates

**Usage:**
```python
from components.charts.config import validate_configuration

report = validate_configuration(config)
print(f"Valid: {report.is_valid}")
print(f"Errors: {len(report.errors)}")
print(f"Warnings: {len(report.warnings)}")
```

### 3. Example Strategies

Five professionally configured trading strategies:

1. **EMA Crossover** (Intermediate, Medium Risk)
   - Classic trend-following with EMA crossovers
   - Best for trending markets, 15m-4h timeframes

2. **Momentum Breakout** (Advanced, High Risk)
   - Fast indicators for momentum capture
   - Volume confirmation, best for volatile markets

3. **Mean Reversion** (Intermediate, Medium Risk)
   - Oversold/overbought conditions
   - Multiple RSI periods, best for ranging markets

4. **Scalping** (Advanced, High Risk)
   - Ultra-fast indicators for 1m-5m trading
   - Tight risk management, high frequency

5. **Swing Trading** (Beginner, Medium Risk)
   - Medium-term trend following
   - 4h-1d timeframes, suitable for part-time traders

## Configuration System

### Indicator Definitions

Each indicator has a complete schema definition:

```python
@dataclass
class ChartIndicatorConfig:
    indicator_type: IndicatorType
    parameters: Dict[str, Any]
    display_name: str
    color: str
    line_style: LineStyle
    line_width: int
    display_type: DisplayType
```

### Strategy Configuration

Complete strategy definitions include:

```python
@dataclass
class StrategyChartConfig:
    strategy_name: str
    strategy_type: TradingStrategy
    description: str
    timeframes: List[str]
    layout: ChartLayout
    main_chart_height: float
    overlay_indicators: List[str]
    subplot_configs: List[SubplotConfig]
    chart_style: ChartStyle
```

### Default Configurations

26+ indicator presets organized by category:

- **Trend Indicators**: 13 SMA/EMA presets
- **Momentum Indicators**: 9 RSI/MACD presets  
- **Volatility Indicators**: 4 Bollinger Bands configurations

Access via:
```python
from components.charts.config import get_all_default_indicators

indicators = get_all_default_indicators()
trend_indicators = get_indicators_by_category(IndicatorCategory.TREND)
```

## Example Strategies

### EMA Crossover Strategy

```python
from components.charts.config import create_ema_crossover_strategy

strategy = create_ema_crossover_strategy()
config = strategy.config

# Strategy includes:
# - EMA 12, 26, 50 for trend analysis
# - RSI 14 for momentum confirmation  
# - MACD for signal confirmation
# - Bollinger Bands for volatility context
```

### Custom Strategy Creation

```python
from components.charts.config import create_custom_strategy_config

config, errors = create_custom_strategy_config(
    strategy_name="My Strategy",
    strategy_type=TradingStrategy.MOMENTUM,
    description="Custom momentum strategy",
    timeframes=["5m", "15m"],
    overlay_indicators=["ema_8", "ema_21"],
    subplot_configs=[{
        "subplot_type": "rsi",
        "height_ratio": 0.2,
        "indicators": ["rsi_7"]
    }]
)
```

## Validation System

### Comprehensive Validation

```python
from components.charts.config import validate_configuration

# Full validation with detailed reporting
report = validate_configuration(config)

# Check results
if report.is_valid:
    print("✅ Configuration is valid")
else:
    print("❌ Configuration has errors:")
    for error in report.errors:
        print(f"  • {error}")

# Check warnings
if report.warnings:
    print("⚠️ Warnings:")
    for warning in report.warnings:
        print(f"  • {warning}")
```

### Validation Rules Information

```python
from components.charts.config import get_validation_rules_info

rules = get_validation_rules_info()
for rule, info in rules.items():
    print(f"{info['name']}: {info['description']}")
```

## API Reference

### Core Classes

#### `StrategyChartConfig`
Main configuration class for chart strategies.

**Methods:**
- `validate()` → `tuple[bool, List[str]]` - Basic validation
- `validate_comprehensive()` → `ValidationReport` - Detailed validation
- `get_all_indicators()` → `List[str]` - Get all indicator names
- `get_indicator_configs()` → `Dict[str, ChartIndicatorConfig]` - Get configurations

#### `StrategyExample`
Container for example strategies with metadata.

**Properties:**
- `config: StrategyChartConfig` - The strategy configuration
- `description: str` - Detailed strategy description
- `difficulty: str` - Beginner/Intermediate/Advanced
- `risk_level: str` - Low/Medium/High
- `market_conditions: List[str]` - Suitable market conditions

### Utility Functions

#### Configuration Access
```python
# Get all example strategies
get_all_example_strategies() → Dict[str, StrategyExample]

# Filter by criteria  
get_strategies_by_difficulty("Intermediate") → List[StrategyExample]
get_strategies_by_risk_level("Medium") → List[StrategyExample]
get_strategies_by_market_condition("Trending") → List[StrategyExample]

# Get strategy summary
get_strategy_summary() → Dict[str, Dict[str, str]]
```

#### JSON Export/Import
```python
# Export to JSON
export_strategy_config_to_json(config) → str
export_example_strategies_to_json() → str

# Import from JSON
load_strategy_config_from_json(json_data) → tuple[StrategyChartConfig, List[str]]
```

#### Validation
```python
# Comprehensive validation
validate_configuration(config, rules=None, strict=False) → ValidationReport

# Get validation rules info
get_validation_rules_info() → Dict[ValidationRule, Dict[str, str]]
```

## Examples

### Example 1: Using Pre-built Strategy

```python
from components.charts.config import get_example_strategy

# Get a specific strategy
strategy = get_example_strategy("ema_crossover")

print(f"Strategy: {strategy.config.strategy_name}")
print(f"Difficulty: {strategy.difficulty}")
print(f"Risk Level: {strategy.risk_level}")
print(f"Timeframes: {strategy.config.timeframes}")
print(f"Indicators: {strategy.config.overlay_indicators}")

# Validate before use
is_valid, errors = strategy.config.validate()
if is_valid:
    # Use in dashboard
    pass
```

### Example 2: Creating Custom Configuration

```python
from components.charts.config import (
    StrategyChartConfig, SubplotConfig, ChartStyle,
    TradingStrategy, SubplotType, ChartLayout
)

# Create custom configuration
config = StrategyChartConfig(
    strategy_name="Custom Momentum Strategy",
    strategy_type=TradingStrategy.MOMENTUM,
    description="Fast momentum strategy with volume confirmation",
    timeframes=["5m", "15m"],
    layout=ChartLayout.MAIN_WITH_SUBPLOTS,
    main_chart_height=0.65,
    overlay_indicators=["ema_8", "ema_21", "bb_20_25"],
    subplot_configs=[
        SubplotConfig(
            subplot_type=SubplotType.RSI,
            height_ratio=0.15,
            indicators=["rsi_7"],
            title="Fast RSI"
        ),
        SubplotConfig(
            subplot_type=SubplotType.VOLUME,
            height_ratio=0.2,
            indicators=[],
            title="Volume Confirmation"
        )
    ],
    chart_style=ChartStyle(
        theme="plotly_white",
        candlestick_up_color="#00d4aa",
        candlestick_down_color="#fe6a85"
    )
)

# Comprehensive validation
report = config.validate_comprehensive()
print(f"Validation: {report.summary()}")
```

### Example 3: Filtering Strategies

```python
from components.charts.config import (
    get_strategies_by_difficulty,
    get_strategies_by_market_condition
)

# Get beginner-friendly strategies
beginner_strategies = get_strategies_by_difficulty("Beginner")
print("Beginner Strategies:")
for strategy in beginner_strategies:
    print(f"  • {strategy.config.strategy_name}")

# Get strategies for trending markets
trending_strategies = get_strategies_by_market_condition("Trending")
print("\nTrending Market Strategies:")
for strategy in trending_strategies:
    print(f"  • {strategy.config.strategy_name}")
```

### Example 4: Validation with Error Handling

```python
from components.charts.config import validate_configuration, ValidationLevel

# Validate with comprehensive reporting
report = validate_configuration(config)

# Handle different severity levels
if report.errors:
    print("🚨 ERRORS (must fix):")
    for error in report.errors:
        print(f"  • {error}")

if report.warnings:
    print("\n⚠️ WARNINGS (recommended fixes):")
    for warning in report.warnings:
        print(f"  • {warning}")

if report.info:
    print("\nℹ️ INFO (optimization suggestions):")
    for info in report.info:
        print(f"  • {info}")

# Check specific validation rules
height_issues = report.get_issues_by_rule(ValidationRule.HEIGHT_RATIOS)
if height_issues:
    print(f"\nHeight ratio issues: {len(height_issues)}")
```

## Best Practices

### 1. Configuration Design

- **Use meaningful names**: Strategy names should be descriptive
- **Validate early**: Always validate configurations before use
- **Consider timeframes**: Match timeframes to strategy type
- **Height ratios**: Ensure total height ≤ 1.0

### 2. Indicator Selection

- **Avoid redundancy**: Don't use multiple similar indicators
- **Performance impact**: Limit complex indicators (>3 Bollinger Bands)
- **Category balance**: Mix trend, momentum, and volume indicators
- **Timeframe alignment**: Use appropriate indicator periods

### 3. Strategy Development

- **Start simple**: Begin with proven strategies like EMA crossover
- **Test thoroughly**: Validate both technically and with market data
- **Document well**: Include entry/exit rules and market conditions
- **Consider risk**: Match complexity to experience level

### 4. Validation Usage

- **Use comprehensive validation**: Get detailed reports with suggestions
- **Handle warnings**: Address performance and usability warnings
- **Test edge cases**: Validate with extreme configurations
- **Monitor updates**: Re-validate when changing configurations

### 5. Performance Optimization

- **Limit indicators**: Keep total indicators <10 for performance
- **Monitor memory**: Check resource usage warnings
- **Optimize rendering**: Consider visual complexity
- **Cache configurations**: Reuse validated configurations

## Error Handling

### Common Issues and Solutions

1. **"Indicator not found in defaults"**
   ```python
   # Check available indicators
   from components.charts.config import get_all_default_indicators
   available = get_all_default_indicators()
   print(list(available.keys()))
   ```

2. **"Total height exceeds 1.0"**
   ```python
   # Adjust height ratios
   config.main_chart_height = 0.7
   for subplot in config.subplot_configs:
       subplot.height_ratio = 0.1
   ```

3. **"Invalid timeframe format"**
   ```python
   # Use standard formats
   config.timeframes = ["1m", "5m", "15m", "1h", "4h", "1d", "1w"]
   ```

## Testing

The system includes comprehensive tests:

- **112+ test cases** across all components
- **Unit tests** for individual components
- **Integration tests** for system interactions
- **Validation tests** for error handling

Run tests:
```bash
uv run pytest tests/test_*_strategies.py -v
uv run pytest tests/test_validation.py -v
uv run pytest tests/test_defaults.py -v
```

## Future Enhancements

- **✅ Signal Layer Integration**: Bot trade signals and alerts - **IMPLEMENTED** - See [Bot Integration Guide (`bot-integration.md`)](./bot-integration.md)
- **Custom Indicators**: User-defined technical indicators
- **Advanced Layouts**: Multi-chart and grid layouts
- **Real-time Updates**: Live chart updates with indicator toggling
- **Performance Monitoring**: Advanced resource usage tracking

## Bot Integration

The chart system now includes comprehensive bot integration capabilities:

- **Real-time Signal Visualization**: Live bot signals on charts
- **Trade Execution Tracking**: P&L and trade entry/exit points
- **Multi-Bot Support**: Compare strategies across multiple bots
- **Performance Analytics**: Built-in bot performance metrics

📊 **[Complete Bot Integration Guide (`bot-integration.md`)](./bot-integration.md)** - Comprehensive documentation for integrating bot signals with charts

## Support

For issues, questions, or contributions:

1. Check existing configurations in `example_strategies.py`
2. Review validation rules in `validation.py`
3. Test with comprehensive validation
4. Refer to this documentation

The modular chart system is designed to be extensible and maintainable, providing a solid foundation for advanced trading chart functionality.
---

*Back to [Modules Documentation](../README.md)*