Dispatch Configuration System

Overview

The Dispatch Configuration System provides a flexible, multi-tenant approach to customizing dispatch and scheduling interfaces. It allows each customer to configure event colors, work hours, and accessibility themes specific to their industry and preferences.

Architecture

Configuration Structure

The dispatch configuration is integrated into the existing multi-tenant configuration system, stored within the features.Dispatch configuration object for each customer.

{
  "features": {
    "Dispatch": {
      "eventColors": {
        "byIndustry": { "trucking": "#1976d2", "hvac": "#10b981" },
        "byPriority": { "high": "#dc2626", "medium": "#f59e0b" },
        "byStatus": { "scheduled": "#3b82f6", "completed": "#10b981" }
      },
      "timeline": {
        "workHours": { "start": 8, "end": 18 },
        "gridColors": { "workHour": "#ffffff", "weekend": "#f1f5f9" }
      },
      "themes": {
        "default": "standard",
        "available": ["standard", "high_contrast", "colorblind_friendly"]
      },
      "colorThemes": {
        "high_contrast": { "byPriority": { "high": "#000000" } }
      }
    }
  }
}

Default Configuration Generator

Located at services/config/default-configs/dispatch.js, this module provides industry-specific defaults:

const getDefaultDispatchConfig = (appType, industry) => {
  const config = defaults[appType] || defaults.serviceRepair;
  return { Dispatch: { ...config, colorThemes } };
};

Industry-Specific Defaults

Trucking Industry:

Work Hours: 6:00 AM - 8:00 PM (extended hours for logistics)
Primary Colors: Blue theme for trucking operations
Focus: Long-haul scheduling and fleet management

Service/Repair Industry:

Work Hours: 8:00 AM - 6:00 PM (standard business hours)
Industry Colors: Green (HVAC), Orange (Plumbing), Purple (Electrical)
Focus: Service technician scheduling and work orders

Configuration Management

Storage

Database: MongoDB with flexible configs field in Config model
Caching: In-memory cache with file-based persistence in customer-configs/
Tenant Isolation: Each customer's configuration is isolated by relativeId

API Endpoints

Get Configuration

GET /api/v1/config/{parentCompany}?type=parent

Update Configuration

PUT /api/v1/config/{parentCompany}?type=parent
Body: {
  "configKey": "features",
  "data": {
    "Dispatch": {
      "eventColors": { ... },
      "timeline": { ... }
    }
  },
  "type": "object"
}

Data Models

Event Color Configuration

interface EventColors {
  byIndustry: {
    [industry: string]: string; // Hex color codes
  };
  byPriority: {
    high: string;
    urgent: string;
    medium: string;
    low: string;
  };
  byStatus: {
    // Trucking statuses
    new?: string;
    pending?: string;
    enRoute?: string;
    delivered?: string;
    // Service/Repair statuses
    booked?: string;
    assigned?: string;
    inProgress?: string;
    completed?: string;
    invoiced?: string;
  };
}

Timeline Configuration

interface TimelineConfig {
  workHours: {
    start: number; // Hour (0-23)
    end: number; // Hour (1-24)
  };
  gridColors: {
    workHour: string; // Hex color for work hour cells
    nonWorkHour: string; // Hex color for non-work hour cells
    weekend: string; // Hex color for weekend cells
  };
}

Theme Configuration

interface ThemeConfig {
  default: string; // Currently selected theme
  available: string[]; // Available theme options
}

interface ColorThemes {
  [themeName: string]: {
    byPriority?: Partial<EventColors["byPriority"]>;
    byStatus?: Partial<EventColors["byStatus"]>;
  };
}

Implementation Details

Controller Integration

The dispatch configuration is managed through the existing config controller:

// Get configuration
const config = await Config.findOne({
  relativeId: req.params.id,
  type: "parent",
});

// Update configuration
config.configs = {
  ...config.configs,
  features: {
    ...config.configs.features,
    Dispatch: newDispatchConfig,
  },
};

Backward Compatibility

The system maintains backward compatibility through:

Default Fallbacks: If no dispatch configuration exists, defaults are generated
Gradual Migration: Existing customers automatically get default configurations
Optional Fields: All dispatch configuration fields are optional

Configuration Validation

Input validation ensures:

Color values are valid hex codes (/^#[0-9A-F]{6}$/i)
Work hours are valid (0-24 range)
Theme names match available options
Industry types match supported industries

Security Considerations

Multi-Tenant Isolation

Configuration access restricted by parentCompany ID
JWT token validation required for all configuration endpoints
Row-level security through relativeId filtering

Input Sanitization

const sanitizeHexColor = (color) => {
  if (!/^#[0-9A-F]{6}$/i.test(color)) {
    throw new Error("Invalid hex color format");
  }
  return color.toUpperCase();
};

Performance Considerations

Caching Strategy

In-Memory Cache: Frequently accessed configurations cached in application memory
File-Based Persistence: Configurations persisted to disk for faster startup
Cache Invalidation: Automatic cache clearing on configuration updates

Database Optimization

Indexed queries on relativeId and type fields
Optimized for read-heavy workloads
Minimal write operations with batched updates

Testing

Unit Tests

Located at tests/services/config/dispatch.test.js:

describe("Dispatch Configuration", () => {
  test("should return default trucking dispatch config", () => {
    const config = getDefaultDispatchConfig("trucking", "transportation");
    expect(config.Dispatch.timeline.workHours.start).toBe(6);
  });
});

Integration Tests

Test the full configuration flow:

Default generation
API CRUD operations
Cache behavior
Multi-tenant isolation

Error Handling

Common Error Scenarios

Invalid Color Format: Returns 400 with validation error
Missing Parent Company: Returns 404 with tenant not found
Invalid Work Hours: Returns 400 with range validation error
Theme Not Found: Falls back to 'standard' theme
Null Dispatch Configuration: Automatically replaced with default configuration during merge

Error Response Format

{
  "error": "Invalid configuration",
  "details": {
    "field": "eventColors.byPriority.high",
    "message": "Invalid hex color format",
    "received": "#invalid"
  },
  "code": "VALIDATION_ERROR"
}

Migration Guide

Existing Customers

Existing customers automatically receive default dispatch configurations on their next login. However, some customers may have Dispatch: null in their configuration due to previous implementation issues.

Fixing Null Dispatch Configurations

If you encounter customers with Dispatch: null configurations, run the provided migration script:

# Run the fix script to clean up null dispatch configurations
node scripts/fix-null-dispatch-configs.js

This script will:

Find all configurations with Dispatch: null
Remove the null values so defaults can be applied
Fix nested structure issues (features.features)
Clear the configuration cache

Custom Configurations

For customers requiring specific color schemes:

Use the configuration API to set custom colors
Leverage themes for accessibility requirements
Adjust work hours based on operational needs

API Reference

Configuration Endpoints

Get Dispatch Configuration

GET /api/v1/config/{parentCompany}?type=parent
Authorization: Bearer {jwt_token}

Update Event Colors

PUT /api/v1/config/{parentCompany}?type=parent
Content-Type: application/json
Authorization: Bearer {jwt_token}

{
  "configKey": "features",
  "data": {
    "Dispatch": {
      "eventColors": {
        "byIndustry": {
          "trucking": "#1976d2"
        }
      }
    }
  },
  "type": "object"
}

Reset to Defaults

PUT /api/v1/config/{parentCompany}?type=parent
Content-Type: application/json
Authorization: Bearer {jwt_token}

{
  "configKey": "features",
  "data": {
    "Dispatch": null
  },
  "type": "object"
}

Overview​

Architecture​

Configuration Structure​

Default Configuration Generator​

Industry-Specific Defaults​

Configuration Management​

Storage​

API Endpoints​

Data Models​

Event Color Configuration​

Timeline Configuration​

Theme Configuration​

Implementation Details​

Controller Integration​

Backward Compatibility​

Configuration Validation​

Security Considerations​

Multi-Tenant Isolation​

Input Sanitization​

Performance Considerations​

Caching Strategy​

Database Optimization​

Testing​

Unit Tests​

Integration Tests​

Error Handling​

Common Error Scenarios​

Error Response Format​

Migration Guide​

Existing Customers​

Fixing Null Dispatch Configurations​

Custom Configurations​

API Reference​

Configuration Endpoints​

Get Dispatch Configuration​

Update Event Colors​

Reset to Defaults​

Monitoring and Logging​

Metrics to Track​

Logging​

Future Enhancements​

Planned Features​

Scalability Considerations​