Skip to content

AGENTS.md

Latest commit

 

History

History
211 lines (160 loc) · 10.5 KB

AGENTS.md

File metadata and controls

211 lines (160 loc) · 10.5 KB

CLAUDE.md

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

Essential Commands

Development

  • pnpm run dev - Start development environment (TypeScript watch + Relay watch + React dev server under Portless on *.localhost:1355)

Build and Production

  • pnpm run build - Full production build (cleans build/web/, copies resources, builds React via Vite with vite-plugin-pwa service worker generation, builds workspace packages)
  • pnpm run build:react-only - Build only React app via Vite
  • pnpm run relay - Compile GraphQL queries with Relay compiler

Quality Control

  • pnpm run lint - Run ESLint (exits with 0 to not break builds)
  • pnpm run lint-fix - Auto-fix ESLint issues
  • pnpm run format - Check code formatting with Prettier
  • pnpm run format-fix - Auto-fix code formatting

Testing

  • pnpm run test - Run Vitest tests (root: scripts/, src/)
  • pnpm run test (in /react directory) - Run React-specific Vitest tests (pnpm run vitest:watch for watch mode)
  • E2E tests (/e2e/) use Playwright; require full Backend.AI cluster running first

Electron App

  • pnpm run electron:d - Run Electron app in development mode
  • make clean && make dep - Prepare dependencies for Electron
  • make mac / make win / make linux - Build platform-specific apps

Architecture Overview

Architecture

This is a React web application using React 19 + Ant Design 6 + Relay 20 (GraphQL).

Key Technologies

  • React Build: Vite 6 (@vitejs/plugin-react) with vite-plugin-pwa, vite-plugin-svgr, vite-plugin-node-polyfills
  • Component Library Build: Vite (packages/backend.ai-ui/)
  • Service Worker: vite-plugin-pwa (Workbox under the hood), integrated into the Vite build
  • Package Manager: pnpm with workspace monorepo
  • Styling: Ant Design + antd-style
  • State Management: Jotai (global UI state), Relay (server/GraphQL state)
  • GraphQL: Relay compiler with projects for both react/ and packages/backend.ai-ui/
  • React Compiler: babel-plugin-react-compiler in annotation mode ('use memo' directive)
  • Testing: Vitest for unit tests (jsdom env), Playwright for E2E tests
  • Linting: ESLint 9 (flat config) + Prettier, pre-commit hooks via Husky + lint-staged
  • Electron: Desktop app wrapper with built-in websocket proxy
  • Storybook: @storybook/react-vite for backend.ai-ui component library

Project Structure

react/                  # Main React application (Vite)
  src/                  # Application source code
    components/         # React UI components
    pages/              # Page-level components
    hooks/              # Custom React hooks
    helper/             # Utility functions
    __generated__/      # Relay compiler output
  vite.config.ts        # Vite + plugins (PWA / svgr / node-polyfills) configuration
  vitest.config.ts      # Vitest configuration (unit tests)
packages/               # Monorepo workspace packages
  backend.ai-ui/        # Shared React component library (Vite build)
  backend.ai-webui-docs/# User manual documentation
  eslint-config-bai/    # Shared ESLint configuration
src/                    # Utilities and websocket proxy
  lib/                  # Backend.AI client library (ESM/Node.js)
  wsproxy/              # WebSocket proxy for desktop app
resources/              # Static assets, i18n files (22 languages), themes
data/                   # GraphQL schema files (schema.graphql, client-directives.graphql)
e2e/                    # Playwright E2E tests
electron-app/           # Electron desktop app source
configs/                # Environment-specific config files
scripts/                # Build and dev utility scripts

Build Pipeline

Production build (pnpm run build) runs these steps sequentially:

  1. Clean and create build/web/ output directory
  2. Copy index.html, resources/, manifest/, config files
  3. pnpm run -r --stream build builds all workspace packages:
    • React app (Vite) → react/build/ → copied to build/web/
    • Service worker (sw.js) generated by vite-plugin-pwa during the React build
    • backend.ai-ui (Vite) → packages/backend.ai-ui/dist/

Development Workflow

  1. Dev Server: Run pnpm run dev (TypeScript watch + Relay watch + React dev server under Portless). Portless is a devDependency, no global install needed; dev.mjs auto-starts the daemon on port 1355 (HTTPS by default).
  2. URL: For branches matching FR-XXXX the dev URL is https://fr-XXXX.localhost:1355; otherwise Portless derives a branch-based subdomain (printed on startup). See DEV_ENVIRONMENT.md for theme color and troubleshooting.
  3. Testing: Vitest unit tests + Playwright E2E tests
  4. Linting: ESLint 9 (flat config) + Prettier with pre-commit hooks via Husky

Additional Workflow Description

  • All work items are created in Jira and serve as the starting point for understanding and resolving tasks.

  • Work items are cloned as GitHub issues in the corresponding repository.

  • GitHub PR titles follow this format:

    • prefix
      • feat: New features or feature improvements and changes
      • fix: Bug fixes
      • refactor: Refactoring
      • style: Design changes without functional changes
      • chore: Other small tasks
    • Format: prefix(JIRA-ISSUE-NUMBER): title
    • GitHub PR content starts with Resolves #1234(FR-1234) where #1234 is the cloned issue number and FR-1234 is the Jira issue number

  • Tool Requirements:

    • Jira: Use jira-workflow skill (fw plugin). Project config in .jira.config.
    • GitHub: Use gh CLI (preferred) or GitHub MCP (mcp__github__*)
    • Git/PR: Use Graphite MCP (mcp__graphite__run_gt_cmd) for branch/commit/push
      • Do NOT use git commit, git push, git checkout -b directly
      • Allowed: git status, git diff, git add, git log, git stash

  • Follow Graphite's Stacked PR strategy. Write work by appropriately stacking individual PRs.

  • When amending a PR with significant changes, update the PR description to reflect the new scope. Minor fixes don't need description updates, but new features, deleted files, or changed approach should be reflected.

Configuration

  • Main config: config.toml (copied from config.toml.sample)
  • Multiple environments supported via configs/ directory
  • Electron app config: build/electron-app/app/config.toml

Key Libraries

  • react 19, react-dom 19 - UI framework
  • antd 6 - Ant Design component library
  • react-relay 20, relay-runtime 20 - GraphQL client
  • jotai - Atomic state management
  • i18next, react-i18next - Internationalization
  • vite 6 + @vitejs/plugin-react - React app bundler and dev server
  • vitest 4 - Unit test runner (jsdom env)
  • electron 35 - Desktop app framework

GraphQL/Relay Setup

  • Schema files in /data/ (schema.graphql, client-directives.graphql)
  • Relay compiler configured for two projects: react and backend.ai-ui
  • Config: /relay.config.js (extends /relay-base.config.js)
  • Generated types output to react/src/__generated__/ and packages/backend.ai-ui/src/__generated__/
  • Run pnpm run relay to compile GraphQL queries
  • Run pnpm run relay:watch for watch mode during development

Internationalization

  • JSON translation files in resources/i18n/ (22 languages supported)
  • React components use useTranslation() hook from react-i18next
  • Backend.AI UI package has own locale files in packages/backend.ai-ui/src/locale/
  • Run make i18n to extract translation strings

Build Output

  • Production build: build/web/ (contains React build + service worker + static assets)
  • Electron app: build/electron-app/ (created by make dep)
  • Component library: packages/backend.ai-ui/dist/

Important Notes

  • Pre-commit hooks (Husky + lint-staged) run linting and formatting automatically
  • Use make clean before building if encountering issues
  • Electron app requires special build process with make dep
  • React components use Relay; ensure GraphQL schema in /data/ is up to date
  • Backend.AI client library is a workspace package at packages/backend.ai-client/ (built with tsup)

Core Guidelines

React Essentials (detail: .github/instructions/react.instructions.md, auto-loaded via applyTo)

  • Use 'use memo' directive at the top of component bodies for React Compiler optimization. Never remove existing 'use memo'.
  • Use BAIButton action prop for async operations (auto loading state). Prefer BAI components over Ant Design equivalents.
  • Follow Relay fragment architecture: query orchestrator (useLazyLoadQuery) + fragment component (useFragment).
  • Fragment prop naming: queryRef for Query types, {typeName}Frgmt for others.
  • Use useBAILogger instead of console.log. Use pre-defined error boundaries (BAIErrorBoundary, ErrorBoundaryWithNullFallback).
  • Use Jotai for global state, Relay for GraphQL state.

On-Demand Skills (loaded only when needed)

  • Storybook: storybook-guide skill (CSF 3, meta config, story patterns, checklists)
  • i18n: i18n-guide skill (translation keys, casing rules, language-specific guidelines)
  • Documentation: docs-guide skill (user manual structure, terminology, multilingual rules)
  • Relay: relay-patterns skill (fragment architecture, naming conventions, query optimization)

Auto-Applied Instructions (loaded when editing matching files)

  • react.instructions.md → react/**/*.tsx,react/**/*.ts
  • storybook.instructions.md → packages/backend.ai-ui/**/*.stories.tsx,packages/backend.ai-ui/**/*.stories.ts
  • i18n.instructions.md → resources/i18n/**/*.json,packages/backend.ai-ui/src/locale/**/*.json (use i18n-guide skill for tsx/ts context)
  • e2e.instructions.md → e2e/**/*.ts
  • docs.instructions.md → packages/backend.ai-webui-docs/**/*.md

Verification Harness

Run bash scripts/verify.sh from project root to check Relay, Lint, Format, and TypeScript. Output ends with === ALL PASS === on success. Agents should use this script instead of running checks individually.

PR Review Checklist

When reviewing PRs (especially agent-generated ones), check:

  • Verification results (scripts/verify.sh output in PR description)
  • Semantic correctness: does the code do what the issue asks? (lint/tsc passing is not enough)
  • i18n keys match actual UI text and follow naming conventions
  • No unintended scope creep (files changed beyond what the issue requires)
  • TODO(needs-backend) markers are properly placed with issue references
  • No hardcoded strings, magic numbers, or debug artifacts left behind