From 92c82a5518d54cff9e715294c4bf7a6cb3e23dd9 Mon Sep 17 00:00:00 2001 From: Anto01 Date: Wed, 14 Jan 2026 20:42:48 -0500 Subject: [PATCH] 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 --- .../frontend/src/components/canvas/README.md | 177 ++++++++++++++++++ 1 file changed, 177 insertions(+) create mode 100644 atomizer-dashboard/frontend/src/components/canvas/README.md diff --git a/atomizer-dashboard/frontend/src/components/canvas/README.md b/atomizer-dashboard/frontend/src/components/canvas/README.md new file mode 100644 index 00000000..1aed9e44 --- /dev/null +++ b/atomizer-dashboard/frontend/src/components/canvas/README.md @@ -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