|
|
@@ -0,0 +1,149 @@
|
|
|
+# 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](https://github.com/gpustack/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
|
|
|
+
|
|
|
+```bash
|
|
|
+# 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
|
