Chapter 15: Frontend Architecture

The MATIH frontend is a suite of nine React/TypeScript/Vite applications -- called workbenches -- that provide specialized user interfaces for every domain of the platform. Each workbench is an independent single-page application sharing a common foundation of 102 shared components, 28+ hooks, 16 API client modules, and cross-workbench state management through a centralized shared library. This chapter provides a comprehensive examination of the frontend architecture, from the shared library that unifies the suite through the domain-specific workbenches that deliver the platform's capabilities to end users.

What You Will Learn

By the end of this chapter, you will understand:

The workbench architecture including how nine independent React applications share code through a unified library of 102 components, 28+ hooks, and 16 API client modules
The shared component library with reusable UI primitives for navigation, authentication, data visualization, code editing, accessibility, and cross-workbench collaboration
State management patterns combining Zustand for cross-workbench preferences and entity handoff, Redux Toolkit for complex domain state, and a custom lightweight store with middleware support
The API client layer built on the native Fetch API with httpOnly cookie authentication, CSRF protection, automatic retries with exponential backoff, request cancellation, and unified pagination normalization across Java and Python backends
The BI Workbench (64 components) for dashboard building, chart creation, semantic model management, metrics libraries, and AI-assisted data exploration
The ML Workbench (41 components) for AutoML wizards, DNN builder, experiment tracking, model registry, deployment management, and monitoring
The Data Workbench (50 components) for catalog browsing, lineage visualization, ontology building, pipeline editing, dbt editing, and query execution
The Agentic Workbench (85 components) for agent studio, workflow canvas, agent registry, marketplace, approval workflows, and chain-of-thought visualization
The Ops Workbench (32 components) for operational dashboards, observability health, incidents, and conversational ops agent
The Control Plane UI (56 components) for platform administration, executive dashboards, user management, billing, audit, and privacy
The Data Plane UI (34 components) for the unified shell, workbench routing, command palette, and navigation
The Onboarding UI (11 components) for guided first-time user experience with persona selection and connection setup
Real-time infrastructure including WebSocket connection management, Server-Sent Events for streaming, presence tracking, and live notification delivery

Chapter Structure

Section	Description	Audience
Technology Stack	React, Vite, TypeScript, Tailwind CSS configuration and tooling	Frontend developers, architects
Shared Component Library	102 shared components, design system primitives, and cross-workbench utilities	Frontend developers, designers
State Management	Zustand stores, Redux Toolkit, custom store with middleware, cross-tab synchronization	Frontend developers, architects
Authentication and API Client	Fetch-based client, httpOnly cookie auth, CSRF, retries, pagination normalization, 16 service modules	Frontend developers, security engineers
Shared Library Deep Dive	Detailed breakdowns of API clients, hooks, stores, auth, realtime, editors, and more	Frontend developers
BI Workbench	Dashboard builder, chart library, filters, widgets, semantic models, metrics, AI chat	BI developers, data analysts
ML Workbench	AutoML wizard, DNN builder, model registry, experiments, deployment, monitoring	ML engineers, data scientists
Data Workbench	Catalog browser, lineage viewer, ontology builder, pipeline editor, dbt, query editor	Data engineers, catalog admins
Agentic Workbench	Agent studio, workflow canvas, registry, marketplace, approvals, chain-of-thought	AI engineers, business analysts
Ops Workbench	Operations dashboard, observability, incidents, conversational chat interface	Platform operators, SREs
Control Plane UI	Auth pages, executive dashboard, user management, billing, audit, privacy, provisioning	Platform administrators
Onboarding UI	Welcome flow, persona selection, connection setup, guided first query	New users, product managers

Architecture at a Glance

The frontend suite consists of nine workbench applications, each served as an independent Vite-built SPA, connected through shared libraries and cross-workbench state synchronization via the Data Plane UI unified shell.

                    +----------------------------------+
                    |        Browser / Client           |
                    +----------------------------------+
                    |                                    |
    +----------+----------+----------+----------+-------+------+----------+
    |          |          |          |          |       |      |          |
    v          v          v          v          v       v      v          v
 BI Work-  Data Work- ML Work-  Agentic   Control  Ops    Onboard-  Data Plane
  bench      bench     bench   Workbench  Plane   Work-    ing     UI (Shell)
 (3000)     (3002)    (3001)   (3003)     UI      bench    UI
                                         (3004)  (3005)
    |          |          |          |       |       |        |          |
    +----------+----------+----------+-------+-------+--------+----------+
                                    |
                        +-----------+-----------+
                        |   @matih/shared       |
                        |  (102 components)     |
                        |  (28+ hooks)          |
                        |  (16 API clients)     |
                        |  (Zustand stores)     |
                        +-----------+-----------+
                                    |
                    +---------------+---------------+
                    |               |               |
              API Gateway     WebSocket       SSE Streaming
              (8080)          Server           Server

Workbench Summary

Workbench	Components	Port	Key Technologies
`bi-workbench`	64	3000	Vega-Lite, Recharts, react-grid-layout
`ml-workbench`	41	3001	React Flow, D3.js, MLflow integration
`data-workbench`	50	3002	React Flow, Monaco Editor, Dagre
`agentic-workbench`	85	3003	React Flow, Monaco Editor, SSE
`control-plane-ui`	56	3004	React Router, Recharts
`data-plane-ui`	34	3005	Module Federation, Zustand
`ops-workbench`	32	-	Recharts, Tailwind CSS
`onboarding-ui`	11	-	Framer Motion, step wizard
`shared`	102	-	Zustand, Monaco, WebSocket

Cross-Workbench Communication

The platform uses several mechanisms for cross-workbench communication:

BroadcastChannel API -- The crossWorkbenchStore uses the browser's BroadcastChannel API (matih-cross-workbench channel) to synchronize entity selection, navigation requests, and global filters across browser tabs.
LocalStorage persistence -- Zustand's persist middleware stores selected entities, catalog context, and global time ranges in localStorage for cross-session persistence.
Unified Shell routing -- The Data Plane UI's WorkbenchRouter loads workbenches via module federation or lazy imports, providing seamless navigation between domains.
WebSocket channels -- The shared WebSocketProvider enables real-time data subscription across workbenches via channel-based pub/sub messaging.

Source Code Organization

frontend/
  shared/                    # @matih/shared - the shared library
    src/
      api/                   # 16 API client modules
      components/            # 102 reusable components (33 directories)
      hooks/                 # 28+ custom React hooks
      stores/                # Zustand stores (cross-workbench, preferences)
      state/                 # Custom store framework with middleware
      realtime/              # WebSocket, SSE, presence, notifications
      observability/         # Frontend telemetry and error tracking
      services/              # Offline manager, semantic cache
      styles/                # Design tokens (colors, typography, spacing)
      types/                 # Canonical type definitions
      utils/                 # Utilities (API client, validation, config)
  bi-workbench/              # BI analytics workbench
  ml-workbench/              # ML/AI workbench
  data-workbench/            # Data engineering workbench
  agentic-workbench/         # Agentic AI workbench
  ops-workbench/             # Operations workbench
  control-plane-ui/          # Platform administration UI
  data-plane-ui/             # Unified shell and workbench router
  onboarding-ui/             # First-time user onboarding flow

Semantic Layer Technology Stack