Dashboard Builder

The Dashboard Builder is SCRIPE's enterprise-grade admin preference system that syncs 61 customizable dashboard settings between the browser and server. It uses a 4-layer merge engine (Platform → Tenant → Admin → Runtime) to resolve settings with tenant-level override control, cross-device persistence via AdminSettingsJson, and 5 edge case protections including FOUC prevention, tab-close keepalive, and field-level 409 conflict resolution.

System Overview

The Dashboard Builder provides a complete admin preference lifecycle — from immediate cache-first rendering to background server reconciliation. Every admin gets 61 customizable settings covering layout, colors, typography, component styles, and accessibility, all persisted to the server and synced across devices.

4-Layer Merge Engine

Settings follow a strict 4-layer precedence chain. Each layer can override the previous, with optional path-level access control at the tenant layer. This architecture enables white-label deployments where tenant administrators enforce brand standards while still allowing individual admins to personalize their workspace within allowed boundaries.

Server Sync Hook

The useAdminSettingsSync hook manages the complete lifecycle of admin settings: initial load from cache, deferred flush of pending changes from previous sessions, background server fetch, silent reconciliation, debounced save on changes, and tab-close protection. The hook is wired in DashboardLayout — the root client component for all authenticated pages.

// In DashboardLayout (authenticated layout root):
const { isSettingsReady } = useAdminSettingsSync();

// Shimmer only on first-ever device login (no cache)
if (!isSettingsReady) {
  return <LoadingShimmer />;
}

Widget & Grid Configuration Schema

Each widget placed on the dashboard builder canvas is a positioned block on a 12-column CSS Grid. The builder configures their columns, rows, alignment, specific props, zIndex, and visibility, and serializes these into the DashboardThemeJson alongside existing theme tokens.

export interface DashboardWidget {
  id: string;                      // Unique identifier
  type: DashboardWidgetType;       // 'statsCard' | 'chart' | 'dataTable' | 'quickActions' | ...
  gridColumn: string;              // CSS Grid span configuration (e.g. "1 / 7")
  gridRow: string;                 // CSS Grid row configuration (e.g. "1 / 3")
  alignment: WidgetAlignment;      // 'start' | 'center' | 'end' | 'stretch'
  props: Record<string, unknown>;  // Element specific settings (title, chartType, customUrl)
  zIndex: number;                  // Overlap layer control
  visible: boolean;                // Hide/show toggle
}

export interface DashboardBuilderCanvas {
  enabled: boolean;                // True if layout customization is enabled
  widgets: DashboardWidget[];      // Collection of positioned dashboard widgets
  gridRows: number;                // Configured row height (default: 6)
}

Edge Case Protections

The sync system handles 5 critical edge cases that are common in real-world enterprise deployments where admins work across multiple devices, close tabs without saving, and occasionally have network interruptions.

Settings Reference (61 Settings)

All 61 settings are organized into 9 sections. Each setting has a defined type, default value, DOM data-attribute for CSS theming, and an optional edition gate that controls which subscription tier can access it.

Admin Override Control

Tenant administrators can control which settings individual admins are allowed to customize. When AllowAdminThemeOverride is true, the AllowedAdminSettingsJson field contains a JSON whitelist of setting paths that admins can modify. Settings not in the whitelist are rendered as read-only with a lock indicator.

Security Model

The Dashboard Builder implements defense-in-depth security to prevent cross-admin data leakage, payload overflow, and unauthorized settings modification.

Architecture & File Map

The Dashboard Builder is implemented across 7 files in the core layer, following SCRIPE's provider-based architecture pattern. The sync hook and providers handle all state management, while the layout component serves as the entry point.

src/core/providers/
├── useAdminSettingsSync.ts    # Server sync hook (5 edge case protections)
├── settings-provider.tsx      # 4-layer merge engine + field tracking
├── tenant-branding-provider.tsx # Layer 3 sync + override metadata

src/core/config/
├── storage-keys.ts            # Centralized localStorage key definitions
├── api-endpoints.ts           # Dashboard builder API endpoint constants

src/core/ui/layout/
├── dashboard-layout.tsx       # FOUC shimmer gate (layout entry point)

src/modules/auth/core/data/
├── repositories/AuthRepository.ts  # Logout cleanup (raw key removal)

src/modules/monitoring/dashboard/
├── domain/entities/DashboardWidget.ts # 12-column widget schema
├── presentation/components/dashboard-builder/DashboardBuilderPanel.tsx # DnD wrapper
└── presentation/viewmodels/useDashboardBuilderStore.ts # Zustand layout manager