UI Architecture

Internal architecture reference for contributors to the Michelangelo UI codebase.

Technology Stack

Technology	Version	Purpose
React	18.3.1	UI component library
TypeScript	5.7.x	Type-safe JavaScript
BaseUI	15.0.0	Component library
Styletron	6.1.x	CSS-in-JS styling engine
TanStack React Query	5.39.0	Server state management
TanStack React Table	8.21.x	Table components
React Final Form	6.5.9	Form state management
Vite	6.2.0	Build tooling and dev server
Vitest	3.x	Testing framework
Connect RPC	2.0.x	gRPC-Web communication

Package Structure

The JavaScript codebase is organized as a Yarn workspace with the following packages:

javascript/
├── app/                    # Main application package
│   └── package.json        # @michelangelo/app
├── packages/
│   ├── core/               # Core UI components and utilities
│   │   └── package.json    # @uber/michelangelo-core
│   └── rpc/                # RPC client and error handling
│       └── package.json    # @michelangelo/rpc
└── package.json            # Workspace root

Package Responsibilities

@michelangelo/app: The main application that runs in the browser. Contains:

• Application entry point and routing
• Feature-specific views and pages
• Application-level configuration

@uber/michelangelo-core: Shared UI components and utilities. Contains:

• React components (table, cell, form, views)
• React hooks (routing, queries, mutations)
• Provider components (service, error, interpolation)
• Type definitions
• Test utilities

@michelangelo/rpc: RPC client and error handling. Contains:

• Connect RPC client configuration
• Error normalization for Connect errors

Build and Bundling

Development

Start the development server:

cd javascript
yarn dev

This runs Vite in development mode with hot module replacement.

Production Build

Build all packages:

cd javascript
yarn build

Build order:

1. Generate gRPC client code (yarn generate)
2. Build @uber/michelangelo-core
3. Build @michelangelo/rpc
4. Build @michelangelo/app

Scripts

Script	Description
yarn dev	Start development server
yarn build	Build all packages
yarn test	Run all tests
yarn test:core	Run core package tests
yarn test:rpc	Run RPC package tests
yarn lint	Run ESLint
yarn typecheck	Run TypeScript type checking
yarn format	Check code formatting with Prettier

Import Aliases

The codebase uses TypeScript path aliases:

// In @uber/michelangelo-core
import { useStudioQuery } from '#core/hooks/use-studio-query';
import { Phase } from '#core/types/common/studio-types';

// In @michelangelo/rpc
import { normalizeConnectError } from '#rpc/normalize-connect-error';

Related Documentation

• Core Systems - Providers, hooks, and error handling
• Types and Patterns - TypeScript types and React component patterns
• UI Components - Table, cell, form, and styling systems
• Configuration API - Defining phases, entities, and views