docs(canvas): Add comprehensive Canvas documentation
- Architecture overview and file structure - Node types reference table - Data flow diagram - Usage instructions for building workflows - Template and import documentation - Intent JSON schema reference - State management API - Validation rules - Chat integration details Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
177
atomizer-dashboard/frontend/src/components/canvas/README.md
Normal file
177
atomizer-dashboard/frontend/src/components/canvas/README.md
Normal file
@@ -0,0 +1,177 @@
|
||||
# Atomizer Canvas - Visual Optimization Workflow Builder
|
||||
|
||||
A React Flow-based node graph editor for building FEA optimization workflows visually.
|
||||
|
||||
## Overview
|
||||
|
||||
The Canvas provides a visual interface for constructing optimization configurations. Users drag nodes from a palette, connect them to define data flow, configure parameters, and execute with Claude.
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
Canvas System
|
||||
├── lib/canvas/ # Core logic
|
||||
│ ├── schema.ts # Node type definitions
|
||||
│ ├── intent.ts # Graph → Intent JSON serialization
|
||||
│ ├── validation.ts # Graph validation rules
|
||||
│ ├── templates.ts # Pre-built workflow templates
|
||||
│ └── index.ts # Exports
|
||||
├── components/canvas/ # UI components
|
||||
│ ├── nodes/ # 8 node type components
|
||||
│ ├── palette/ # Drag source palette
|
||||
│ ├── panels/ # Config, validation, chat panels
|
||||
│ └── AtomizerCanvas.tsx # Main canvas component
|
||||
├── hooks/ # State management
|
||||
│ ├── useCanvasStore.ts # Zustand store
|
||||
│ ├── useCanvasChat.ts # Chat bridge
|
||||
│ └── useIntentParser.ts # Message parsing
|
||||
└── pages/
|
||||
└── CanvasView.tsx # Canvas page
|
||||
```
|
||||
|
||||
## Node Types
|
||||
|
||||
| Node | Icon | Description | Inputs | Outputs |
|
||||
|------|------|-------------|--------|---------|
|
||||
| Model | 📦 | NX model file (.prt, .fem, .sim) | - | 1 |
|
||||
| Solver | ⚙️ | Nastran solution type (SOL101-112) | 1 | 1 |
|
||||
| DesignVar | 📐 | Parameter with min/max bounds | - | 1 |
|
||||
| Extractor | 🔬 | Physics quantity extraction | 1 | 1 |
|
||||
| Objective | 🎯 | Optimization goal (min/max) | 1 | 1 |
|
||||
| Constraint | 🚧 | Limit condition (<=, >=) | 1 | 1 |
|
||||
| Algorithm | 🧠 | Optimization method (TPE, CMA-ES, etc.) | 1+ | 1 |
|
||||
| Surrogate | 🚀 | Neural network acceleration | 1 | - |
|
||||
|
||||
## Data Flow
|
||||
|
||||
```
|
||||
[DesignVar]──┐
|
||||
├──▶[Model]──▶[Solver]──▶[Extractor]──┬──▶[Objective]──┬──▶[Algorithm]──▶[Surrogate]
|
||||
[DesignVar]──┘ └──▶[Constraint]─┘
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
### Building a Workflow
|
||||
|
||||
1. **Drag nodes** from the left palette onto the canvas
|
||||
2. **Connect nodes** by dragging from output handles (right) to input handles (left)
|
||||
3. **Configure nodes** by clicking to open the config panel
|
||||
4. **Validate** to check for errors/warnings
|
||||
5. **Execute** to send to Claude for processing
|
||||
|
||||
### Using Templates
|
||||
|
||||
Click "Templates" to load pre-configured workflows:
|
||||
- **Mass Minimization** - Single-objective mass reduction
|
||||
- **Multi-Objective Pareto** - Trade-off analysis with NSGA-II
|
||||
- **Turbo Mode** - Accelerated optimization with MLP surrogate
|
||||
- **Mirror Zernike** - Optical surface optimization
|
||||
- **Frequency Optimization** - Modal analysis with SOL103
|
||||
|
||||
### Importing Configurations
|
||||
|
||||
Click "Import" to load existing configurations:
|
||||
- **File Upload** - Select an `optimization_config.json` file
|
||||
- **Paste JSON** - Paste configuration directly
|
||||
- **Load Study** - Load from existing study by name
|
||||
|
||||
## Intent JSON Format
|
||||
|
||||
The canvas serializes to an Intent JSON for Claude:
|
||||
|
||||
```json
|
||||
{
|
||||
"version": "1.0",
|
||||
"source": "canvas",
|
||||
"timestamp": "2026-01-14T...",
|
||||
"model": {
|
||||
"path": "path/to/model.prt",
|
||||
"type": "prt"
|
||||
},
|
||||
"solver": {
|
||||
"type": "SOL101"
|
||||
},
|
||||
"design_variables": [
|
||||
{ "name": "thickness", "min": 1.0, "max": 10.0, "unit": "mm" }
|
||||
],
|
||||
"extractors": [
|
||||
{ "id": "E4", "name": "BDF Mass", "config": {} }
|
||||
],
|
||||
"objectives": [
|
||||
{ "name": "mass", "direction": "minimize", "weight": 1.0, "extractor": "E4" }
|
||||
],
|
||||
"constraints": [
|
||||
{ "name": "max_disp", "operator": "<=", "value": 0.5, "extractor": "E1" }
|
||||
],
|
||||
"optimization": {
|
||||
"method": "TPE",
|
||||
"max_trials": 100
|
||||
},
|
||||
"surrogate": {
|
||||
"enabled": true,
|
||||
"type": "MLP",
|
||||
"min_trials": 20
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## State Management
|
||||
|
||||
Uses Zustand for state management:
|
||||
|
||||
```typescript
|
||||
const {
|
||||
nodes, // Current nodes
|
||||
edges, // Current edges
|
||||
selectedNode, // Currently selected node ID
|
||||
validation, // Validation result
|
||||
|
||||
// Actions
|
||||
addNode, // Add node at position
|
||||
updateNodeData, // Update node configuration
|
||||
onConnect, // Handle edge creation
|
||||
validate, // Run validation
|
||||
toIntent, // Serialize to Intent JSON
|
||||
loadFromIntent, // Load graph from Intent
|
||||
loadFromConfig, // Load from optimization_config.json
|
||||
clear, // Clear canvas
|
||||
} = useCanvasStore();
|
||||
```
|
||||
|
||||
## Validation Rules
|
||||
|
||||
The canvas validates:
|
||||
- **Required nodes**: Model, Solver, Objective, Algorithm
|
||||
- **Minimum counts**: At least 1 design variable, 1 extractor
|
||||
- **Valid connections**: Based on VALID_CONNECTIONS map
|
||||
- **Node configuration**: All required fields filled
|
||||
- **Connectivity**: Objectives must have connected extractors
|
||||
|
||||
## Chat Integration
|
||||
|
||||
The canvas integrates with Claude via:
|
||||
- **Validate** - Get intelligent feedback on workflow
|
||||
- **Analyze** - Get optimization recommendations
|
||||
- **Execute with Claude** - Create study and optionally run optimization
|
||||
|
||||
## Files
|
||||
|
||||
### Core Schema
|
||||
- `lib/canvas/schema.ts` - All node data types and connection rules
|
||||
|
||||
### Components
|
||||
- `nodes/BaseNode.tsx` - Base node with handles, status, animations
|
||||
- `nodes/*.tsx` - Specific node implementations
|
||||
- `palette/NodePalette.tsx` - Draggable node list
|
||||
- `panels/NodeConfigPanel.tsx` - Node configuration form
|
||||
- `panels/ValidationPanel.tsx` - Error/warning display
|
||||
- `panels/ChatPanel.tsx` - Claude response display
|
||||
- `panels/ExecuteDialog.tsx` - Study name input
|
||||
- `panels/ConfigImporter.tsx` - Import configuration dialog
|
||||
- `panels/TemplateSelector.tsx` - Template selection dialog
|
||||
|
||||
### Hooks
|
||||
- `useCanvasStore.ts` - Main state store
|
||||
- `useCanvasChat.ts` - Chat bridge for Claude interaction
|
||||
- `useIntentParser.ts` - Parse Claude messages for canvas updates
|
||||
Reference in New Issue
Block a user