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

CLAUDE.md 6.1 KB Trvalý odkaz Historie Surový