maas-base-ui/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

GPUStack UI — Dashboard/management UI for GPUStack, a GPU model serving and management platform. Features include model deployment, playground (chat/embedding/rerank/image/speech), resource management, cluster management, benchmark, and access control.

Tech Stack

• Framework: UmiJS Max 4.x (@umijs/max) — enterprise React framework with built-in routing, state, request, access, locale, and layout plugins
• UI Library: Ant Design 6.x (antd) + Pro Components (@ant-design/pro-components)
• Core UI package: @gpustack/core-ui — shared internal UI components
• State Management: Jotai (atomic state via src/atoms/)
• HTTP Client: Axios via Umi request layer
• Build Tool: Webpack (via Umi)
• Language: TypeScript
• Package Manager: pnpm
• Styling: Less + CSS modules + styled-components + antd-style

Key Commands

# Install dependencies
pnpm install

# Start dev server (http://localhost:9000)
npm run dev          # or: pnpm dev

# Production build
npm run build

# Preview build output
npm run preview

# Format code
npm run format

# Check locale files
npm run check:locales

Environment variables:

• PROXY_HOST — API proxy target for dev server
• ENABLE_ENTERPRISE — enable enterprise features
• ENABLE_PLAYGROUND — enable playground section (default: true)
• APP_TITLE — custom app title

Project Structure

config/                 # Umi build configuration
  config.ts             # Main config (proxy, build, plugins, routes)
  routes.ts             # Route definitions (main entry for navigation structure)
  routes.extensions.ts  # Build-time route extensions
  proxy.ts              # Dev proxy configuration
  plugins.ts            # Webpack plugins (compression, monaco)
  keep-alive.ts         # Route keep-alive configuration
  mfsu.extensions.ts    # MFSU exclusions
src/
  app.tsx               # App entry: getInitialState, request config, plugin initialization
  access.ts             # Role-based access control (canSeeAdmin, canSeeOrgAdmin, etc.)
  request-config.tsx    # Axios interceptors, error handling, 401 redirect
  global.tsx            # Global setup (dayjs plugins)
  global.less           # Global styles
  atoms/                # Jotai atomic state (user, settings, models, clusters, etc.)
  config/               # Runtime config (settings, theme, hotkeys, breakpoints)
  layouts/              # Custom layout system (sidebar, menu, logo, error boundary)
  pages/                # Page components (feature-based subdirectories)
    _components/        # Shared page-level components
    dashboard/          # Dashboard
    playground/         # Chat, embedding, rerank, images, speech
    llmodels/           # Model catalog, user models, deployments
    model-routes/       # Model routing
    usage/              # Usage statistics
    maas-provider/      # Model providers
    benchmark/          # Benchmark tests
    gpu-service/        # GPU service (instances, templates, storage, public keys)
    resources/          # Workers, GPUs, backends, modelfiles
    cluster-management/ # Clusters, credentials
    users/              # User management
    api-keys/           # API key management
    login/              # Login page
    profile/            # User profile
  components/           # Global shared components
  plugins/              # Plugin system (manager, enterprise-ready, locale merger)
  services/             # API service layer (minimal, most API calls are inline)
  locales/              # i18n locale files
  assets/               # Images, logos, provider logos
  request.extensions.ts # Build-time request interceptor hooks (empty by default)
  access.extensions.ts  # Build-time access extension hooks (empty by default)

Architecture Patterns

Routing

• Hash-based routing (history.type: 'hash')
• Routes defined in config/routes.ts with icon, access control, and keep-alive support
• Route extensions applied via config/routes.extensions.ts for build-time plugin injection

Authentication & Access Control

• Umi access plugin with predicate-based role checks
• Key predicates: canSeeAdmin, canSeeOrgAdmin, canManageCurrentOrg, canSeeUser, canDelete, canLogin
• 401 responses trigger logout → redirect to /login
• First-login flow redirects admin to /resources/workers

State Management

• Jotai atoms in src/atoms/ for global state (user info, settings, pagination, route cache, etc.)
• Umi initialState for currentUser and fetchUserInfo
• Persistent storage via setAtomStorage / clearAtomStorage utilities

HTTP Requests

• Base URL: /v2 (GPUSTACK_API_BASE_URL)
• OpenAI-compatible APIs: /v1
• Special paths (/auth, /v1, /version, /proxy, /update) bypass the API base URL
• Request/response interceptors in src/request-config.tsx
• Extension point: src/request.extensions.ts (empty by default, populated by build-time tooling)

Plugin System

• GPUStackPluginManager in src/plugins/manager.ts
• Plugins register with onAppInit and onAppReady lifecycle hooks
• Enterprise plugin loaded via src/plugins/enterprise-ready.ts
• Build-time extensions populate *.extensions.ts files

Layout

• Custom layout in src/layouts/ with sidebar, menu, logo, right panel
• Error boundary and exception pages
• Render links and extra render hooks for plugin injection

Internationalization

• Umi locale plugin with en-US default
• Ant Design locale auto-synced
• Locale files in src/locales/

Important Notes

• The .extensions.ts files (routes.extensions.ts, request.extensions.ts, access.extensions.ts, etc.) are generated at build time by external tooling — do not edit them directly
• Monaco Editor is integrated via @monaco-editor/react and monaco-editor-webpack-plugin
• XTerm.js used for terminal/console output
• Markdown rendering with react-markdown + GFM + KaTeX math support
• The project uses hash routing, so all routes have #/ prefix in the browser