TCPDashboard/docs/modules/charts

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
• Architecture
• Quick Start
• Components
• User Indicator Management
• Configuration System
• Example Strategies
• Validation System
• API Reference
• Examples
• 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

# 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).

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) - Comprehensive guide to the indicator system
• ⚡ Quick Guide: Adding New Indicators (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

# 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

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

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:

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:

@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:

@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:

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

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

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

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

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

# 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

# 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

# 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

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

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

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

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"

   # 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"

   # Adjust height ratios
   config.main_chart_height = 0.7
   for subplot in config.subplot_configs:
       subplot.height_ratio = 0.1
   

3. "Invalid timeframe format"

   # 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:

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)
• 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) - 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