MATIH Platform is in active MVP development. Documentation reflects current implementation status.
15. Workbench Architecture
Shared Component Library

Shared Component Library

The @matih/shared library is the foundation of the MATIH frontend, providing 102 reusable components, 28+ custom hooks, 16 API client modules, and shared state management across all nine workbenches. Located at frontend/shared/src/, this library ensures consistent behavior, design language, and API integration patterns across the entire platform.


Library Organization

shared/src/
  api/                  # 16 API client modules
    client.ts           # Base ApiClient class
    bi.ts               # BIApiClient
    query.ts            # QueryApiClient
    semantic.ts         # SemanticApiClient
    ai.ts               # AIApiClient
    ml.ts               # MLApiClient
    data.ts             # DataApiClient
    pipeline.ts         # PipelineApiClient
    dbt.ts              # DbtApiClient
    dataQuality.ts      # DataQualityApiClient
    governance.ts       # GovernanceApiClient
    ontology.ts         # OntologyApiClient
    render.ts           # RenderApiClient
    opsAgent.ts         # OpsAgentApiClient
    agentStudio.ts      # AgentStudioApiClient
    notification.ts     # NotificationApiClient
    billing.ts          # BillingApiClient
  components/           # 102 reusable components in 33 directories
    Auth/               # Authentication (AuthGuard, LoginForm, ProtectedRoute, etc.)
    Navigation/         # Navigation (Sidebar, TopNavigation, GlobalSearch, etc.)
    ErrorBoundary/      # Error handling (ErrorBoundary, WidgetErrorBoundary)
    Loading/            # Loading states (Skeleton, LoadingSpinner, LoadingOverlay)
    MonacoEditor/       # Code editors (SqlEditor)
    Collaboration/      # Multi-user (PresenceIndicator, CommentsPanel, ShareDialog)
    Toast/              # Notifications (Toast, ToastProvider)
    Lineage/            # Data lineage (LineageGraph, LineageNode, LineageEdge)
    Portal/             # Dashboard portal (WelcomeHeader, QuickActions, etc.)
    StatusPanel/        # Status displays (StatusBar, SLAPanel, etc.)
    ... (20+ more)
  hooks/                # 28+ custom React hooks
  stores/               # Zustand stores
  state/                # Custom store framework
  realtime/             # WebSocket, SSE, presence
  observability/        # Frontend telemetry
  services/             # Offline, semantic cache
  styles/               # Design tokens
  types/                # Canonical types
  utils/                # Shared utilities

Component Categories

Authentication (8 components)

ComponentFilePurpose
AuthGuardAuth/AuthGuard.tsxSession verification and route protection
AuthProviderAuth/AuthProvider.tsxAuthentication context provider
LoginFormAuth/LoginForm.tsxLogin form with validation
RegisterFormAuth/RegisterForm.tsxUser registration form
ProtectedRouteAuth/ProtectedRoute.tsxRoute-level auth gating
PermissionGuardAuth/PermissionGuard.tsxPermission-based content gating
SessionManagerAuth/SessionManager.tsxSession lifecycle management
ProfileManagerAuth/ProfileManager.tsxUser profile editing

Navigation (12 components)

ComponentFilePurpose
SidebarNavigation/Sidebar.tsxCollapsible side navigation
TopNavigationNavigation/TopNavigation.tsxTop header bar with search and user menu
GlobalSearchNavigation/GlobalSearch.tsxPlatform-wide search
UserMenuNavigation/UserMenu.tsxUser profile dropdown
TenantSelectorNavigation/TenantSelector.tsxMulti-tenant switcher
PersonaSwitcherNavigation/PersonaSwitcher.tsxRole-based UI switching
EnvironmentSwitcherNavigation/EnvironmentSwitcher.tsxDev/staging/prod switching
NotificationCenterNavigation/NotificationCenter.tsxNotification drawer
CIStatusBadgeNavigation/CIStatusBadge.tsxCI/CD status indicator

Error Handling (4 components)

ComponentFilePurpose
ErrorBoundaryErrorBoundary/ErrorBoundary.tsxReact error boundary with Sentry integration
WidgetErrorBoundaryErrorBoundary/WidgetErrorBoundary.tsxWidget-level error isolation
WorkbenchErrorBoundaryErrorBoundary/WorkbenchErrorBoundary.tsxWorkbench-level error handling
withErrorBoundaryErrorBoundary/withErrorBoundary.tsxHOC for error boundary wrapping

Observability (1 component, 5 hooks)

Component/HookFilePurpose
ObservabilityProviderobservability/ObservabilityProvider.tsxRoot-level provider that initializes Sentry, Web Vitals, session tracking, and global error handlers
useTrackEventobservability/hooks.tsTrack custom analytics events
useTrackPageobservability/hooks.tsTrack page views with automatic route detection
useErrorCaptureobservability/hooks.tsCapture and report errors with component context
useObservabilityobservability/hooks.tsAccess the full ObservabilityManager instance

ObservabilityProvider Usage

All 8 workbenches wrap their root component with ObservabilityProvider as the outermost provider:

import { ObservabilityProvider } from '@matih/shared';
 
export function App() {
  return (
    <ObservabilityProvider appName="bi-workbench">
      <ErrorBoundary name="BiWorkbench">
        {/* App content */}
      </ErrorBoundary>
    </ObservabilityProvider>
  );
}

Props:

PropTypeDefaultDescription
appNamestring (required)-Identifies the workbench in telemetry
appVersionstring'1.0.0'App version for release tracking
sentryDsnstring-Sentry DSN for error tracking
environmentstring'development'Environment name
enableWebVitalsbooleantrueTrack Core Web Vitals (CLS, LCP, INP, FCP, TTFB)
enableSessionTrackingbooleantrueTrack user session lifecycle
enableGlobalErrorHandlersbooleantrueCatch uncaught errors and unhandled promise rejections

Workbench Integration Status:

WorkbenchappNameStatus
ops-workbenchops-workbenchIntegrated
bi-workbenchbi-workbenchIntegrated
data-workbenchdata-workbenchIntegrated
ml-workbenchml-workbenchIntegrated
agentic-workbenchagentic-workbenchIntegrated
control-plane-uicontrol-plane-uiIntegrated
data-plane-uidata-plane-uiIntegrated
onboarding-uionboarding-uiIntegrated

Visualization and Data (15+ components)

ComponentFilePurpose
LineageGraphLineage/LineageGraph.tsxInteractive lineage visualization
LineageNodeLineage/LineageNode.tsxCustom lineage graph node
LineageEdgeLineage/LineageEdge.tsxCustom lineage graph edge
PlatformAnalyticsAnalytics/PlatformAnalytics.tsxCross-tenant analytics dashboard
SystemHealthPanelTelemetry/SystemHealthPanel.tsxSystem health overview
UsageMetricsTelemetry/UsageMetrics.tsxPlatform usage metrics
BillingDashboardBilling/BillingDashboard.tsxBilling overview
AuditLogViewerAudit/AuditLogViewer.tsxAudit event viewer

For detailed breakdowns of each component category, see the Shared Library Deep Dive section.