CLAUDE.md · bytedance/flowgram.ai

Sections

1. Repository Overview
2. Build System & Package Management
3. Monorepo Structure
4. Key Design Patterns
5. Testing
6. Code Quality
7. Commit & Pull Request Standards
8. Working with Packages
9. Common Issues
10. Additional Resources

First lines (shown under the repo's MIT license)

# CLAUDE.md

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

## Repository Overview

FlowGram is a composable, visual workflow development framework built as a Rush-managed monorepo. It provides tools for building AI workflow platforms, including a flow canvas, node configuration forms, variable scope chains, and pre-built materials (LLM, Condition, Code Editor, etc.).

## Build System & Package Management

This monorepo uses **Rush 5.150.0** with **pnpm 10.6.5** as the package manager. Node.js version must be >=18.20.3 <19.0.0 || >=20.14.0 <23.0.0.

### Essential Commands

```bash
# Install dependencies (required first step)
rush install

# Build all packages
rush build

# Build specific package and its dependencies
rush build --to @flowgram.ai/core

# Lint all packages
rush lint

# Fix lint issues
rush lint:fix

# TypeScript type checking
rush ts-check

# Run unit tests
rush test

# Run tests with coverage
rush test:cov

# Build packages in watch mode (for development)
rush build:watch

# E2E tests with Playwright
rush e2e:test

# Update E2E screenshots
rush e2e:update-screenshot
```

### Development Commands for Demos

```bash
# Run docs site with hot reload
rush dev:docs

# Run specific demo apps with hot reload
rush dev:demo-free-layout
rush dev:demo-fixed-layout
rush dev:demo-fixed-layout-simple
rush dev:demo-free-layout-simple
rush dev:demo-nextjs
rush dev:demo-nextjs-antd
```

These commands use `concurrently` to run `rush build:watch` for dependencies alongside the demo's dev server.

### Single Package Development

To work on a single package in isolation:
```bash
cd packages/canvas-engine/core
rushx build        # Runs the build script for this package only
rushx test         # Runs tests for this package only
rushx ts-check     # Type checks this package only
```

## Monorepo Structure

### Core Organization

- **`packages/`** - Production libraries organized by functional area:
  - `canvas-engine/` - Canvas rendering and layout systems (core, document, renderer, fixed-layout-core, free-layout-core)
  - `node-engine/` - Node data and form management (node, form, form-core)
  - `variable-engine/` - Variable scoping and type inference (variable-core, variable-layout, json-schema)
  - `runtime/` - Workflow execution engines (interface, js-core, nodejs)
  - `plugins/` - Extensibility modules (23+ plugins for features like history, drag, snap, minimap, etc.)
  - `client/` - High-level React components (editor, fixed-layout-editor, free-layout-editor, playground-react)
  - `materials/` - Pre-built node materials (form-materials, form-antd-materials, fixed-semi-materials, coze-editor, type-editor)
  - `common/` - Shared utilities (utils, reactive, command, history, history-storage, i18n)

- **`apps/`** - Demos and documentation:
  - `docs/` - Main documentation site
  - `demo-*/` - Example applications (free-layout, fixed-layout, nextjs, vite, playground, etc.)
  - `create-app/`, `cli/` - CLI tools for scaffolding

- **`e2e/`** - End-to-end test suites (fixed-layout, free-layout)
- **`config/`** - Shared configuration (eslint-config, ts-config)
- **`common/`** - Rush tooling and scripts

### Architectural Layers

FlowGram is architected in distinct layers:

1. **Canvas Engine Layer** (`@flowgram.ai/core`, `@flowgram.ai/document`, `@flowgram.ai/renderer`)
   - Core abstractions for canvas rendering, document model, and viewport management
   - Supports two layout modes: free-layout (drag-anywhere) and fixed-layout (structured positioning)
   - Plugin-based architecture using dependency injection (inversify)

2. **Node Engine Layer** (`@flowgram.ai/node`, `@flowgram.ai/form`, `@flowgram.ai/form-core`)
   - Manages node data structures and lifecycle
   - Form engine with validation, side effects, linkage, and error capture
   - Uses `FormModelV2` (exported as `FormModel` from `@flowgram.ai/editor`)

3. **Variable Engine Layer** (`@flowgram.ai/variable-core`, `@flowgram.ai/json-schema`)
   - Provides variable scoping, structure inspection, and type inference
   - Manages data flow constraints across workflow nodes
   - Scope chain mechanism for variable resolution

4. **Runtime Layer** (`@flowgram.ai/runtime-js`, `@flowgram.ai/runtime-nodejs`, `@flowgram.ai/runtime-interface`)
   - Executes workflows in JavaScript/Node.js environments
   - Interface package defines runtime contracts
   - Separate implementations for browser and server

5. **Client/Editor Layer** (`@flowgram.ai/editor`, `@flowgram.ai/fixed-layout-editor`, `@flowgram.ai/free-layout-editor`)
   - High-level React components that integrate all subsystems
   - `@flowgram.ai/editor` is the main barrel export for fixed-layout workflows
   - Re-exports from core, form, variable, and plugin packages

6. **Plugin Ecosystem**
   - 20+ plugins providing features like drag-and-drop, history/undo, snap-to-grid, minimap, auto-layout, etc.
   - Plugins are registered via dependency injection containers
   - Naming convention: `free-*-plugin` for free-layout, `fixed-*-plugin` for fixed-layout, or generic plugins

## Key Design Patterns

### Dependency Injection
The codebase heavily uses **inversify** for dependency injection. Services are decorated with `@injectable()` and injected via `@inject()`. Container modules organize related services.

### Reactive State Management
Uses a custom reactive system (`@flowgram.ai/reactive`) with React hooks:
- `ReactiveState` and `ReactiveBaseState` for observable state
- `useReactiveState`, `useReadonlyReactiveState`, `useObserve` hooks
- `Tracker` for dependency tracking

### Command Pattern
`@flowgram.ai/command` provides a command/command registry system for undo/redo operations. Re-exported by `@flowgram.ai/core`.

### Plugin Architecture
Plugins extend functionality via:
- `Plugin` interface from `@flowgram.ai/core`
- Registration through container modules
- Lifecycle hooks (`onInit`, `onDestroy`, etc.)

## Testing

- **Unit tests**: Use Vitest, located in `__tests__/` folders or `*.test.ts` files
- **E2E tests**: Use Playwright, located in `e2e/*/tests/` directories
- Run all tests: `rush test`
- Run E2E tests for specific package: `rush e2e:test --to @flowgram.ai/e2e-free-layout`
- Update Playwright snapshots: `rush e2e:update-screenshot`