System Overview

Architecture Hierarchy

dashboard_lego/
├── core/                  # Core orchestration and state management
│   ├── page.py           # DashboardPage: main orchestrator
│   ├── state.py          # StateManager: publisher/subscriber coordination
│   ├── datasource.py     # DataSource: concrete data interface (v0.15)
│   ├── data_builder.py   # DataBuilder: data construction (v0.15)
│   ├── data_transformer.py # DataTransformer: data transformation (v0.15)
│   ├── theme.py          # ThemeConfig: styling system
│   └── datasources/      # Concrete data source implementations
│       ├── csv_source.py
│       ├── parquet_source.py
│       └── sql_source.py
├── blocks/               # Visual components
│   ├── base.py          # BaseBlock: abstract block interface
│   ├── typed_chart.py   # TypedChartBlock: unified chart block (v0.15)
│   ├── metrics_factory.py # get_metric_row: factory for metrics (v0.15+)
│   ├── single_metric.py  # SingleMetricBlock: individual metric (v0.15+)
│   └── text.py          # TextBlock: markdown/HTML rendering
├── presets/             # Pre-built blocks and layouts
│   ├── eda_presets.py   # EDA visualization blocks
│   ├── ml_presets.py    # Machine learning visualization blocks
│   ├── layouts.py       # Layout composition functions
│   └── control_styles.py # UI styling utilities
└── utils/               # Utilities
    ├── exceptions.py    # Custom exception hierarchy
    ├── logger.py        # Logging configuration
    └── formatting.py    # Data formatting utilities

Module Dependency Graph

DashboardPage (orchestrator)
    ├─> StateManager (state coordination)
    ├─> ThemeConfig (styling)
    ├─> BaseBlock (components)
    │   ├─> DataSource (data)
    │   └─> StateManager (registration)
    └─> Navigation (multi-section pages)

BaseBlock (abstract)
    ├─> TypedChartBlock (replaces Static/Interactive)
    ├─> ControlPanelBlock
    ├─> get_metric_row() (factory, replaces MetricsBlock/KPIBlock)
    └─> SingleMetricBlock (individual metric block)
    └─> TextBlock

DataSource (concrete, uses composition)
    ├─> DataBuilder (build stage)
    └─> DataTransformer (transform stage)

Presets (convenience)
    ├─> EDA Presets (extends TypedChartBlock)
    └─> ML Presets (extends TypedChartBlock)

Core Design Principles

  1. Modularity: Each block is independent and reusable

  2. Publisher/Subscriber Pattern: Loose coupling through state management

  3. Caching: Transparent disk-based caching at datasource level

  4. Type Safety: Full type hints for IDE and static analysis support

  5. Theme System: Consistent styling across all components

  6. Block-Centric Callbacks: One callback per block for performance