Configurable Dashboard System

Overview

The configurable dashboard system allows you to define dashboard metric cards using JSON configuration, making it easy to add, remove, or modify cards without changing code. The system supports both legacy data sources (current dashboard endpoints) and new generic entity endpoints.

Architecture

Components

1. Configuration (src/constants/dashboardConfig.js)

   • Defines card structure and properties
   • Maps cards to data sources
   • Configures display properties

2. Generic Card Component (src/components/dashboard/ConfigurableMetricCard.jsx)

   • Renders any card based on configuration
   • Handles loading, error, and data states
   • Supports dynamic units and colors

3. Data Hooks (src/hooks/useEntityMetrics.jsx)

   • useEntityMetrics: For new generic endpoints
   • useLegacyDashboardMetrics: For current dashboard data

4. Dashboard Widget (src/components/dashboard/ConfigurableDashboardMetrics.jsx)

   • Orchestrates card rendering
   • Manages data flow
   • Handles error states

Configuration Structure

{
  "id": "junction-pressure",
  "title": "Junction Pressure",
  "entity": "Junction",
  "attribute": "pressure",
  "aggregators": ["avg", "min", "max"],
  "icon": "mdi:gauge",
  "color": "info",
  "unit": "auto",
  "dataSource": "realtime"
}

Configuration Properties

• id: Unique identifier for the card
• title: Display title for the card
• entity: Entity type (Junction, System, Water, etc.)
• attribute: Attribute to measure (pressure, demand, leakage, age)
• aggregators: Array of aggregations to display (avg, min, max, sum, count)
• icon: Material Design Icons identifier
• color: Theme color (primary, secondary, info, warning, error, success)
• unit: Unit display strategy ("auto" uses API response, or specific unit)
• dataSource: Data source ("realtime", "quality", "summary")

Current Cards

1. Junction Pressure - Real-time pressure metrics from junctions
2. Junction Demand - Real-time demand metrics from junctions
3. System Leakage - Real-time leakage metrics from system
4. Water Age - Quality metrics for water age

Migration Strategy

Phase 1: Configuration-Driven Cards (Completed)

• ✅ Cards defined in JSON configuration
• ✅ Generic card component created
• ✅ Legacy data mapping implemented
• ✅ Dashboard updated to use new system

Phase 2: Generic API Endpoints (Completed)

• ✅ Create /api/Aggregate/Hydr endpoint
• ✅ Create /api/Aggregate/Qual endpoint
• ✅ Support individual requests: /api/Aggregate/Hydr?entityType=Junction&attribute=pressure&aggregator=avg&scenarioId=1&decimalPrecision=1
• ✅ Support cross-table aggregation (entityType can be null)
• ✅ Batch multiple aggregators in single requests

Phase 3: Full Migration (Completed)

• ✅ Switched from legacy to generic endpoints
• ✅ Removed legacy data mapping
• ✅ Cleaned up legacy dashboard service files
• ✅ Removed legacy dashboard endpoints
• 🔄 Add database-driven configuration (future enhancement)

API Endpoints

Current (Generic - Active)

• GET /api/Aggregate/Hydr?entityType={entity}&attribute={attribute}&aggregator={aggregator}&scenarioId={scenarioId}&decimalPrecision={precision}
• GET /api/Aggregate/Qual?entityType={entity}&attribute={attribute}&aggregator={aggregator}&scenarioId={scenarioId}&decimalPrecision={precision}
• POST /api/Aggregate/Hydr/batch - Batch requests for efficiency (future)

Legacy (Removed)

• GET /api/dashboard/realtime - Removed
• GET /api/dashboard/quality - Removed
• GET /api/dashboard/summary - Removed

New Array Aggregator Support

The API now supports requesting multiple aggregations in a single call by providing comma-separated aggregator values:

Single Aggregator (Legacy):

GET /api/Aggregate/Hydr?entityType=Junction&attribute=pressure&aggregator=avg&scenarioId=1

Multiple Aggregators (New):

GET /api/Aggregate/Hydr?entityType=Junction&attribute=pressure&aggregator=avg,min,max&scenarioId=1

Response Format:

{
  "values": {
    "avg": 45.2,
    "min": 32.1,
    "max": 67.8
  },
  "unit": "psi",
  "metadata": {
    "aggregators": ["avg", "min", "max"],
    "attribute": "pressure",
    "entityType": "junction",
    "scenarioId": 1,
    "timestamp": 1234567890,
    "decimalPrecision": 2
  }
}

Benefits:

• Performance: Single API call instead of multiple requests
• Efficiency: Reduced network overhead
• Consistency: All aggregations use the same timestamp
• Flexibility: Easy to add/remove aggregations without code changes

Adding New Cards

1. Add to Configuration

   // In src/constants/dashboardConfig.js
   {
     id: 'new-metric',
     title: 'New Metric',
     entity: 'EntityType', // or null for cross-table aggregation
     attribute: 'attributeName',
     aggregators: ['avg', 'min', 'max'],
     icon: 'mdi:icon-name',
     color: 'primary',
     unit: 'auto',
     dataSource: 'realtime' // or 'quality' for quality metrics
   }

2. Card appears automatically - No code changes needed!

The system will automatically:

• Generate API requests to the appropriate endpoint (/api/Aggregate/Hydr or /api/Aggregate/Qual)
• Handle cross-table aggregation when entity is null
• Batch multiple aggregators for the same entity/attribute combination
• Display the card with proper units and formatting

Benefits

• Flexibility: Easy to add/remove/modify cards
• Consistency: Standardized card appearance and behavior
• Maintainability: Configuration-driven approach
• Extensibility: Support for new aggregators and data sources
• Performance: Batch API requests for efficiency
• User Experience: Consistent loading states and error handling

Future Enhancements

• Database-driven configuration
• User-customizable dashboards
• Drag-and-drop card reordering
• Card-specific refresh intervals
• Advanced aggregators (percentiles, trends)
• Card templates and themes