TCPDashboard/docs/components/charts/configuration.md

# Chart Configuration System

The Chart Configuration System provides comprehensive management of chart settings, indicator definitions, and trading strategy configurations. It includes schema validation, default presets, and extensible configuration patterns.

## Table of Contents

- [Overview](#overview)
- [Indicator Definitions](#indicator-definitions)
- [Default Configurations](#default-configurations)
- [Strategy Configurations](#strategy-configurations)
- [Validation System](#validation-system)
- [Configuration Files](#configuration-files)
- [Usage Examples](#usage-examples)
- [Extension Guide](#extension-guide)

## Overview

The configuration system is built around three core concepts:

1. **Indicator Definitions** - Schema and validation for technical indicators
2. **Default Configurations** - Pre-built indicator presets organized by category
3. **Strategy Configurations** - Complete chart setups for trading strategies

### Architecture

```
components/charts/config/
├── indicator_defs.py     # Core schemas and validation
├── defaults.py           # Default indicator presets
├── strategy_charts.py    # Strategy configurations
├── validation.py         # Validation system
├── example_strategies.py # Real-world examples
└── __init__.py          # Package exports
```

## Indicator Definitions

### Core Classes

#### `ChartIndicatorConfig`

The main configuration class for individual indicators:

```python
@dataclass
class ChartIndicatorConfig:
    indicator_type: IndicatorType
    parameters: Dict[str, Any]
    display_name: str
    color: str
    line_style: LineStyle = LineStyle.SOLID
    line_width: int = 2
    display_type: DisplayType = DisplayType.OVERLAY
    opacity: float = 1.0
    show_legend: bool = True
```

#### Enums

**IndicatorType**
```python
class IndicatorType(str, Enum):
    SMA = "sma"
    EMA = "ema"
    RSI = "rsi"
    MACD = "macd"
    BOLLINGER_BANDS = "bollinger_bands"
    VOLUME = "volume"
```

**DisplayType**
```python
class DisplayType(str, Enum):
    OVERLAY = "overlay"      # Overlaid on price chart
    SUBPLOT = "subplot"      # Separate subplot
    HISTOGRAM = "histogram"  # Histogram display
```

**LineStyle**
```python
class LineStyle(str, Enum):
    SOLID = "solid"
    DASHED = "dash"
    DOTTED = "dot"
    DASH_DOT = "dashdot"
```

### Schema Validation

#### `IndicatorParameterSchema`

Defines validation rules for indicator parameters:

```python
@dataclass
class IndicatorParameterSchema:
    name: str
    type: type
    required: bool = True
    min_value: Optional[Union[int, float]] = None
    max_value: Optional[Union[int, float]] = None
    default_value: Any = None
    description: str = ""
    valid_values: Optional[List[Any]] = None
```

#### `IndicatorSchema`

Complete schema for an indicator type:

```python
@dataclass
class IndicatorSchema:
    indicator_type: IndicatorType
    display_type: DisplayType
    parameters: List[IndicatorParameterSchema]
    description: str
    calculation_description: str
    usage_notes: List[str] = field(default_factory=list)
```

### Schema Definitions

The system includes complete schemas for all supported indicators:

```python
INDICATOR_SCHEMAS = {
    IndicatorType.SMA: IndicatorSchema(
        indicator_type=IndicatorType.SMA,
        display_type=DisplayType.OVERLAY,
        parameters=[
            IndicatorParameterSchema(
                name="period",
                type=int,
                min_value=1,
                max_value=200,
                default_value=20,
                description="Number of periods for the moving average"
            ),
            IndicatorParameterSchema(
                name="price_column",
                type=str,
                required=False,
                default_value="close",
                valid_values=["open", "high", "low", "close"],
                description="Price column to use for calculation"
            )
        ],
        description="Simple Moving Average - arithmetic mean of prices",
        calculation_description="Sum of closing prices divided by period"
    ),
    # ... more schemas
}
```

### Utility Functions

#### Validation Functions

```python
# Validate individual indicator configuration
def validate_indicator_configuration(config: ChartIndicatorConfig) -> tuple[bool, List[str]]

# Create indicator configuration with validation
def create_indicator_config(
    indicator_type: IndicatorType,
    parameters: Dict[str, Any],
    **kwargs
) -> tuple[Optional[ChartIndicatorConfig], List[str]]

# Get schema for indicator type
def get_indicator_schema(indicator_type: IndicatorType) -> Optional[IndicatorSchema]

# Get available indicator types
def get_available_indicator_types() -> List[IndicatorType]

# Validate parameters for specific type
def validate_parameters_for_type(
    indicator_type: IndicatorType, 
    parameters: Dict[str, Any]
) -> tuple[bool, List[str]]
```

## Default Configurations

### Organization

Default configurations are organized by category and trading strategy:

#### Categories

```python
class IndicatorCategory(str, Enum):
    TREND = "trend"
    MOMENTUM = "momentum"
    VOLATILITY = "volatility"
    VOLUME = "volume"
    SUPPORT_RESISTANCE = "support_resistance"
```

#### Trading Strategies

```python
class TradingStrategy(str, Enum):
    SCALPING = "scalping"
    DAY_TRADING = "day_trading"
    SWING_TRADING = "swing_trading"
    POSITION_TRADING = "position_trading"
    MOMENTUM = "momentum"
    MEAN_REVERSION = "mean_reversion"
```

### Indicator Presets

#### `IndicatorPreset`

Container for pre-configured indicators:

```python
@dataclass
class IndicatorPreset:
    name: str
    config: ChartIndicatorConfig
    category: IndicatorCategory
    description: str
    recommended_timeframes: List[str]
    suitable_strategies: List[TradingStrategy]
    notes: List[str] = field(default_factory=list)
```

### Available Presets

**Trend Indicators (13 presets)**
- `sma_5`, `sma_10`, `sma_20`, `sma_50`, `sma_100`, `sma_200`
- `ema_5`, `ema_12`, `ema_21`, `ema_26`, `ema_50`, `ema_100`, `ema_200`

**Momentum Indicators (9 presets)**
- `rsi_7`, `rsi_14`, `rsi_21`
- `macd_5_13_4`, `macd_8_17_6`, `macd_12_26_9`, `macd_19_39_13`

**Volatility Indicators (4 presets)**
- `bb_10_15`, `bb_20_15`, `bb_20_20`, `bb_50_20`

### Color Schemes

Organized color palettes by category:

```python
CATEGORY_COLORS = {
    IndicatorCategory.TREND: {
        "primary": "#2E86C1",    # Blue
        "secondary": "#5DADE2",  # Light Blue
        "accent": "#1F618D"      # Dark Blue
    },
    IndicatorCategory.MOMENTUM: {
        "primary": "#E74C3C",    # Red
        "secondary": "#F1948A",  # Light Red
        "accent": "#C0392B"      # Dark Red
    },
    # ... more colors
}
```

### Access Functions

```python
# Get all default indicators
def get_all_default_indicators() -> Dict[str, IndicatorPreset]

# Filter by category
def get_indicators_by_category(category: IndicatorCategory) -> Dict[str, IndicatorPreset]

# Filter by timeframe
def get_indicators_for_timeframe(timeframe: str) -> Dict[str, IndicatorPreset]

# Get strategy-specific indicators
def get_strategy_indicators(strategy: TradingStrategy) -> Dict[str, IndicatorPreset]

# Create custom preset
def create_custom_preset(
    name: str,
    indicator_type: IndicatorType,
    parameters: Dict[str, Any],
    category: IndicatorCategory,
    **kwargs
) -> tuple[Optional[IndicatorPreset], List[str]]
```

## Strategy Configurations

### Core Classes

#### `StrategyChartConfig`

Complete chart configuration for a trading strategy:

```python
@dataclass
class StrategyChartConfig:
    strategy_name: str
    strategy_type: TradingStrategy
    description: str
    timeframes: List[str]
    
    # Chart layout
    layout: ChartLayout = ChartLayout.MAIN_WITH_SUBPLOTS
    main_chart_height: float = 0.7
    
    # Indicators
    overlay_indicators: List[str] = field(default_factory=list)
    subplot_configs: List[SubplotConfig] = field(default_factory=list)
    
    # Style
    chart_style: ChartStyle = field(default_factory=ChartStyle)
    
    # Metadata
    created_at: Optional[datetime] = None
    updated_at: Optional[datetime] = None
    version: str = "1.0"
    tags: List[str] = field(default_factory=list)
```

#### `SubplotConfig`

Configuration for chart subplots:

```python
@dataclass
class SubplotConfig:
    subplot_type: SubplotType
    height_ratio: float = 0.3
    indicators: List[str] = field(default_factory=list)
    title: Optional[str] = None
    y_axis_label: Optional[str] = None
    show_grid: bool = True
    show_legend: bool = True
    background_color: Optional[str] = None
```

#### `ChartStyle`

Comprehensive chart styling:

```python
@dataclass
class ChartStyle:
    theme: str = "plotly_white"
    background_color: str = "#ffffff"
    grid_color: str = "#e6e6e6"
    text_color: str = "#2c3e50"
    font_family: str = "Arial, sans-serif"
    font_size: int = 12
    candlestick_up_color: str = "#26a69a"
    candlestick_down_color: str = "#ef5350"
    volume_color: str = "#78909c"
    show_volume: bool = True
    show_grid: bool = True
    show_legend: bool = True
    show_toolbar: bool = True
```

### Default Strategy Configurations

Pre-built strategy configurations for common trading approaches:

1. **Scalping Strategy**
   - Ultra-fast indicators (EMA 5, 12, 21)
   - Fast RSI (7) and MACD (5,13,4)
   - 1m-5m timeframes

2. **Day Trading Strategy**
   - Balanced indicators (SMA 20, EMA 12/26, BB 20,2.0)
   - Standard RSI (14) and MACD (12,26,9)
   - 5m-1h timeframes

3. **Swing Trading Strategy**
   - Longer-term indicators (SMA 50, EMA 21/50, BB 20,2.0)
   - Standard momentum indicators
   - 1h-1d timeframes

### Configuration Functions

```python
# Create default strategy configurations
def create_default_strategy_configurations() -> Dict[str, StrategyChartConfig]

# Create custom strategy
def create_custom_strategy_config(
    strategy_name: str,
    strategy_type: TradingStrategy,
    description: str,
    timeframes: List[str],
    overlay_indicators: List[str],
    subplot_configs: List[Dict[str, Any]],
    **kwargs
) -> tuple[Optional[StrategyChartConfig], List[str]]

# JSON import/export
def load_strategy_config_from_json(json_data: Union[str, Dict[str, Any]]) -> tuple[Optional[StrategyChartConfig], List[str]]
def export_strategy_config_to_json(config: StrategyChartConfig) -> str

# Access functions
def get_strategy_config(strategy_name: str) -> Optional[StrategyChartConfig]
def get_all_strategy_configs() -> Dict[str, StrategyChartConfig]
def get_available_strategy_names() -> List[str]
```

## Validation System

### Validation Rules

The system includes 10 comprehensive validation rules:

1. **REQUIRED_FIELDS** - Validates essential configuration fields
2. **HEIGHT_RATIOS** - Ensures chart height ratios sum correctly
3. **INDICATOR_EXISTENCE** - Checks indicator availability
4. **TIMEFRAME_FORMAT** - Validates timeframe patterns
5. **CHART_STYLE** - Validates styling options
6. **SUBPLOT_CONFIG** - Validates subplot configurations
7. **STRATEGY_CONSISTENCY** - Checks strategy-timeframe alignment
8. **PERFORMANCE_IMPACT** - Warns about performance issues
9. **INDICATOR_CONFLICTS** - Detects redundant indicators
10. **RESOURCE_USAGE** - Estimates resource consumption

### Validation Classes

#### `ValidationReport`

Comprehensive validation results:

```python
@dataclass
class ValidationReport:
    is_valid: bool
    errors: List[ValidationIssue] = field(default_factory=list)
    warnings: List[ValidationIssue] = field(default_factory=list)
    info: List[ValidationIssue] = field(default_factory=list)
    debug: List[ValidationIssue] = field(default_factory=list)
    validation_time: Optional[datetime] = None
    rules_applied: Set[ValidationRule] = field(default_factory=set)
```

#### `ValidationIssue`

Individual validation issue:

```python
@dataclass
class ValidationIssue:
    level: ValidationLevel
    rule: ValidationRule
    message: str
    field_path: str = ""
    suggestion: Optional[str] = None
    auto_fix: Optional[str] = None
    context: Dict[str, Any] = field(default_factory=dict)
```

### Validation Usage

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

# Comprehensive validation
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}")

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

## Configuration Files

### File Structure

```
components/charts/config/
├── __init__.py              # Package exports and public API
├── indicator_defs.py        # Core indicator schemas and validation
├── defaults.py              # Default indicator presets and categories
├── strategy_charts.py       # Strategy configuration classes and defaults
├── validation.py            # Validation system and rules
└── example_strategies.py    # Real-world trading strategy examples
```

### Key Exports

From `__init__.py`:

```python
# Core classes
from .indicator_defs import (
    IndicatorType, DisplayType, LineStyle, PriceColumn,
    IndicatorParameterSchema, IndicatorSchema, ChartIndicatorConfig
)

# Default configurations
from .defaults import (
    IndicatorCategory, TradingStrategy, IndicatorPreset,
    get_all_default_indicators, get_indicators_by_category
)

# Strategy configurations  
from .strategy_charts import (
    ChartLayout, SubplotType, SubplotConfig, ChartStyle, StrategyChartConfig,
    create_default_strategy_configurations
)

# Validation system
from .validation import (
    ValidationLevel, ValidationRule, ValidationIssue, ValidationReport,
    validate_configuration
)

# Example strategies
from .example_strategies import (
    StrategyExample, create_ema_crossover_strategy,
    get_all_example_strategies
)
```

## Usage Examples

### Example 1: Creating Custom Indicator

```python
from components.charts.config import (
    create_indicator_config, IndicatorType
)

# Create custom EMA configuration
config, errors = create_indicator_config(
    indicator_type=IndicatorType.EMA,
    parameters={"period": 21, "price_column": "close"},
    display_name="EMA 21",
    color="#2E86C1",
    line_width=2
)

if config:
    print(f"Created: {config.display_name}")
else:
    print(f"Errors: {errors}")
```

### Example 2: Using Default Presets

```python
from components.charts.config import (
    get_all_default_indicators,
    get_indicators_by_category,
    IndicatorCategory
)

# Get all available indicators
all_indicators = get_all_default_indicators()
print(f"Available indicators: {len(all_indicators)}")

# Get trend indicators only
trend_indicators = get_indicators_by_category(IndicatorCategory.TREND)
for name, preset in trend_indicators.items():
    print(f"{name}: {preset.description}")
```

### Example 3: Strategy Configuration

```python
from components.charts.config import (
    create_custom_strategy_config,
    TradingStrategy
)

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

if config:
    print(f"Created strategy: {config.strategy_name}")
    is_valid, validation_errors = config.validate()
    if is_valid:
        print("Strategy is valid!")
    else:
        print(f"Validation errors: {validation_errors}")
```

### Example 4: Comprehensive Validation

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

# Validate with specific rules
rules = {ValidationRule.REQUIRED_FIELDS, ValidationRule.HEIGHT_RATIOS}
report = validate_configuration(config, rules=rules)

# Detailed error handling
for error in report.errors:
    print(f"ERROR: {error.message}")
    if error.suggestion:
        print(f"  Suggestion: {error.suggestion}")
    if error.auto_fix:
        print(f"  Auto-fix: {error.auto_fix}")

# Performance warnings
performance_issues = report.get_issues_by_rule(ValidationRule.PERFORMANCE_IMPACT)
if performance_issues:
    print(f"Performance concerns: {len(performance_issues)}")
```

## Extension Guide

### Adding New Indicators

1. **Define Indicator Type**
   ```python
   # Add to IndicatorType enum
   class IndicatorType(str, Enum):
       # ... existing types
       STOCHASTIC = "stochastic"
   ```

2. **Create Schema**
   ```python
   # Add to INDICATOR_SCHEMAS
   INDICATOR_SCHEMAS[IndicatorType.STOCHASTIC] = IndicatorSchema(
       indicator_type=IndicatorType.STOCHASTIC,
       display_type=DisplayType.SUBPLOT,
       parameters=[
           IndicatorParameterSchema(
               name="k_period",
               type=int,
               min_value=1,
               max_value=100,
               default_value=14
           ),
           # ... more parameters
       ],
       description="Stochastic Oscillator",
       calculation_description="Momentum indicator comparing closing price to price range"
   )
   ```

3. **Create Default Presets**
   ```python
   # Add to defaults.py
   def create_momentum_indicators():
       # ... existing indicators
       indicators["stoch_14"] = IndicatorPreset(
           name="stoch_14",
           config=create_indicator_config(
               IndicatorType.STOCHASTIC,
               {"k_period": 14, "d_period": 3},
               display_name="Stochastic %K(14,%D(3))",
               color=CATEGORY_COLORS[IndicatorCategory.MOMENTUM]["primary"]
           )[0],
           category=IndicatorCategory.MOMENTUM,
           description="Standard Stochastic oscillator",
           recommended_timeframes=["15m", "1h", "4h"],
           suitable_strategies=[TradingStrategy.SWING_TRADING]
       )
   ```

### Adding New Validation Rules

1. **Define Rule**
   ```python
   # Add to ValidationRule enum
   class ValidationRule(str, Enum):
       # ... existing rules
       CUSTOM_RULE = "custom_rule"
   ```

2. **Implement Validation**
   ```python
   # Add to ConfigurationValidator
   def _validate_custom_rule(self, config: StrategyChartConfig, report: ValidationReport) -> None:
       # Custom validation logic
       if some_condition:
           report.add_issue(ValidationIssue(
               level=ValidationLevel.WARNING,
               rule=ValidationRule.CUSTOM_RULE,
               message="Custom validation message",
               suggestion="Suggested fix"
           ))
   ```

3. **Add to Validator**
   ```python
   # Add to validate_strategy_config method
   if ValidationRule.CUSTOM_RULE in self.enabled_rules:
       self._validate_custom_rule(config, report)
   ```

### Adding New Strategy Types

1. **Define Strategy Type**
   ```python
   # Add to TradingStrategy enum
   class TradingStrategy(str, Enum):
       # ... existing strategies
       GRID_TRADING = "grid_trading"
   ```

2. **Create Strategy Configuration**
   ```python
   # Add to create_default_strategy_configurations()
   strategy_configs["grid_trading"] = StrategyChartConfig(
       strategy_name="Grid Trading Strategy",
       strategy_type=TradingStrategy.GRID_TRADING,
       description="Grid trading with support/resistance levels",
       timeframes=["1h", "4h"],
       overlay_indicators=["sma_20", "sma_50"],
       # ... complete configuration
   )
   ```

3. **Add Example Strategy**
   ```python
   # Create in example_strategies.py
   def create_grid_trading_strategy() -> StrategyExample:
       config = StrategyChartConfig(...)
       return StrategyExample(
           config=config,
           description="Grid trading strategy description...",
           difficulty="Intermediate",
           risk_level="Medium"
       )
   ```

The configuration system is designed to be highly extensible while maintaining type safety and comprehensive validation. All additions should follow the established patterns and include appropriate tests.