feat(canvas): Add file browser, introspection, and improve node flow
Phase 1-7 of Canvas V4 Ralph Loop implementation: Backend: - Add /api/files routes for browsing model files - Add /api/nx routes for NX model introspection - Add NXIntrospector service to discover expressions and extractors - Add health check with database status Frontend: - Add FileBrowser component for selecting .sim/.prt/.fem files - Add IntrospectionPanel to discover expressions and extractors - Update NodeConfigPanel with browse and introspect buttons - Update schema with NODE_HANDLES for proper flow direction - Update validation for correct DesignVar -> Model -> Solver flow - Update useCanvasStore.addNode() to accept custom data Flow correction: Design Variables now connect TO Model (as source), not FROM Model. This matches the actual data flow in optimization. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
452
docs/plans/CANVAS_UX_DESIGN.md
Normal file
452
docs/plans/CANVAS_UX_DESIGN.md
Normal file
@@ -0,0 +1,452 @@
|
||||
# Canvas UX Design - Study Management Flow
|
||||
|
||||
**Created**: January 16, 2026
|
||||
**Status**: Design Phase
|
||||
|
||||
---
|
||||
|
||||
## Problem Statement
|
||||
|
||||
The Canvas Builder needs clear answers to these questions:
|
||||
|
||||
1. **When processing a canvas**, does it overwrite the current study or create a new one?
|
||||
2. **How do users start fresh** - create a new study from scratch?
|
||||
3. **How does the Home page** handle study selection vs. creation?
|
||||
4. **What's the relationship** between Canvas, Dashboard, and study context?
|
||||
|
||||
---
|
||||
|
||||
## Proposed Solution: Study-Aware Canvas
|
||||
|
||||
### Core Concepts
|
||||
|
||||
| Concept | Description |
|
||||
|---------|-------------|
|
||||
| **Study Context** | Global state tracking which study is "active" |
|
||||
| **Canvas Mode** | Either "editing existing" or "creating new" |
|
||||
| **Process Dialog** | Explicit choice: update vs. create new |
|
||||
| **Study Browser** | Unified view for selecting/creating studies |
|
||||
|
||||
---
|
||||
|
||||
## User Flows
|
||||
|
||||
### Flow 1: Open Existing Study → View/Edit → Run
|
||||
|
||||
```
|
||||
Home Page
|
||||
│
|
||||
├── Study List shows all studies with status
|
||||
│ • bracket_v3 [Running] 47/100 trials
|
||||
│ • mirror_wfe_v2 [Paused] 23/50 trials
|
||||
│ • beam_freq [Complete] 100/100 trials
|
||||
│
|
||||
└── User clicks "bracket_v3"
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────┐
|
||||
│ Study: bracket_v3 │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────┐ │
|
||||
│ │ Dashboard │ Results │ Canvas │ │
|
||||
│ └─────────────────────────────────┘ │
|
||||
│ │
|
||||
│ [Run Optimization] [Edit Canvas] │
|
||||
└─────────────────────────────────────┘
|
||||
│
|
||||
├── "Dashboard" → Live monitoring
|
||||
├── "Results" → Reports & analysis
|
||||
└── "Canvas" → View/edit workflow
|
||||
│
|
||||
▼
|
||||
Canvas loads from optimization_config.json
|
||||
Shows all nodes + connections
|
||||
User can modify and re-process
|
||||
```
|
||||
|
||||
### Flow 2: Create New Study from Scratch
|
||||
|
||||
```
|
||||
Home Page
|
||||
│
|
||||
└── User clicks [+ New Study]
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────┐
|
||||
│ Create New Study │
|
||||
│ │
|
||||
│ Study Name: [my_new_bracket_____] │
|
||||
│ │
|
||||
│ Category: [Bracket ▼] │
|
||||
│ ├─ Bracket │
|
||||
│ ├─ Beam │
|
||||
│ ├─ Mirror │
|
||||
│ └─ + New Category... │
|
||||
│ │
|
||||
│ Start with: │
|
||||
│ ● Blank Canvas │
|
||||
│ ○ Template: [Mass Minimization ▼] │
|
||||
│ ○ Copy from: [bracket_v3 ▼] │
|
||||
│ │
|
||||
│ [Cancel] [Create Study] │
|
||||
└─────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
Backend creates folder structure:
|
||||
studies/Bracket/my_new_bracket/
|
||||
├── 1_config/
|
||||
├── 2_iterations/
|
||||
└── 3_results/
|
||||
│
|
||||
▼
|
||||
Opens Canvas in "New Study" mode
|
||||
Header shows: "Creating: my_new_bracket"
|
||||
Canvas is blank (or has template)
|
||||
```
|
||||
|
||||
### Flow 3: Canvas → Process → Create/Update Decision
|
||||
|
||||
```
|
||||
User is in Canvas (either mode)
|
||||
│
|
||||
└── Clicks [Process with Claude]
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────┐
|
||||
│ Generate Optimization │
|
||||
│ │
|
||||
│ Claude will generate: │
|
||||
│ • optimization_config.json │
|
||||
│ • run_optimization.py │
|
||||
│ │
|
||||
│ ─────────────────────────────────────────── │
|
||||
│ │
|
||||
│ If editing existing study: │
|
||||
│ ┌─────────────────────────────────────────┐ │
|
||||
│ │ ● Update current study │ │
|
||||
│ │ Will modify: bracket_v3 │ │
|
||||
│ │ ⚠ Overwrites existing config │ │
|
||||
│ │ │ │
|
||||
│ │ ○ Create new study │ │
|
||||
│ │ Name: [bracket_v4_____________] │ │
|
||||
│ │ □ Copy model files from bracket_v3 │ │
|
||||
│ └─────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ If creating new study: │
|
||||
│ ┌─────────────────────────────────────────┐ │
|
||||
│ │ Creating: my_new_bracket │ │
|
||||
│ │ │ │
|
||||
│ │ Model files needed: │
|
||||
│ │ □ Upload .prt file │
|
||||
│ │ □ Upload .sim file │
|
||||
│ │ - or - │
|
||||
│ │ □ Copy from: [bracket_v3 ▼] │ │
|
||||
│ └─────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ [Cancel] [Generate & Create] │
|
||||
└─────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
Claude processes intent:
|
||||
1. Validates configuration
|
||||
2. Generates optimization_config.json
|
||||
3. Creates run_optimization.py
|
||||
4. If new study: switches context to it
|
||||
│
|
||||
▼
|
||||
Success dialog:
|
||||
┌─────────────────────────────────────┐
|
||||
│ ✓ Study Created Successfully │
|
||||
│ │
|
||||
│ bracket_v4 is ready to run │
|
||||
│ │
|
||||
│ [View Dashboard] [Run Optimization]│
|
||||
└─────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## UI Components
|
||||
|
||||
### 1. Home Page (Redesigned)
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Atomizer [+ New Study]│
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Search studies... 🔍 │ │
|
||||
│ └────────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐│
|
||||
│ │ Recent Studies ││
|
||||
│ │ ││
|
||||
│ │ ┌─────────────────────────────────────────────────────────┐││
|
||||
│ │ │ 🟢 bracket_v3 Running │││
|
||||
│ │ │ Bracket • 47/100 trials • Best: 2.34 kg │││
|
||||
│ │ │ [Dashboard] [Canvas] [Results] │││
|
||||
│ │ └─────────────────────────────────────────────────────────┘││
|
||||
│ │ ││
|
||||
│ │ ┌─────────────────────────────────────────────────────────┐││
|
||||
│ │ │ 🟡 mirror_wfe_v2 Paused │││
|
||||
│ │ │ Mirror • 23/50 trials • Best: 5.67 nm │││
|
||||
│ │ │ [Dashboard] [Canvas] [Results] │││
|
||||
│ │ └─────────────────────────────────────────────────────────┘││
|
||||
│ │ ││
|
||||
│ │ ┌─────────────────────────────────────────────────────────┐││
|
||||
│ │ │ ✓ beam_freq_tuning Completed │││
|
||||
│ │ │ Beam • 100/100 trials • Best: 0.12 Hz error │││
|
||||
│ │ │ [Dashboard] [Canvas] [Results] │││
|
||||
│ │ └─────────────────────────────────────────────────────────┘││
|
||||
│ └─────────────────────────────────────────────────────────────┘│
|
||||
│ │
|
||||
│ Categories: [All] [Bracket] [Beam] [Mirror] │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 2. Study Header (When Study Selected)
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ ← Back bracket_v3 🟢 Running 47/100 │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌──────────┬──────────┬──────────┬──────────┐ │
|
||||
│ │Dashboard │ Results │ Canvas │ Settings │ │
|
||||
│ └──────────┴──────────┴──────────┴──────────┘ │
|
||||
│ │
|
||||
│ [Run Optimization ▶] [Pause ⏸] [Generate Report] │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 3. Canvas Header (Context-Aware)
|
||||
|
||||
**When editing existing study:**
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Canvas Builder Editing: bracket_v3 │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ [Templates] [Import] 5 nodes [Validate] [Process ▶] │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**When creating new study:**
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Canvas Builder Creating: my_new_bracket │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ [Templates] [Import] 0 nodes [Validate] [Create Study ▶] │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 4. Process/Create Dialog
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Generate Optimization ✕ │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ Claude will analyze your workflow and generate: │
|
||||
│ • optimization_config.json │
|
||||
│ • run_optimization.py (using Atomizer protocols) │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────────│
|
||||
│ │
|
||||
│ Save to: │
|
||||
│ │
|
||||
│ ○ Update existing study │
|
||||
│ └─ bracket_v3 (overwrites current config) │
|
||||
│ │
|
||||
│ ● Create new study │
|
||||
│ └─ Study name: [bracket_v4_______________] │
|
||||
│ Category: [Bracket ▼] │
|
||||
│ ☑ Copy model files from bracket_v3 │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────────│
|
||||
│ │
|
||||
│ After creation: │
|
||||
│ ☑ Open new study automatically │
|
||||
│ ☐ Start optimization immediately │
|
||||
│ │
|
||||
│ [Cancel] [Generate] │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Technical Architecture
|
||||
|
||||
### 1. Global Study Context
|
||||
|
||||
```typescript
|
||||
// contexts/StudyContext.tsx
|
||||
|
||||
interface Study {
|
||||
path: string; // "Bracket/bracket_v3"
|
||||
name: string; // "bracket_v3"
|
||||
category: string; // "Bracket"
|
||||
status: 'not_started' | 'running' | 'paused' | 'completed';
|
||||
trialCount: number;
|
||||
maxTrials: number;
|
||||
bestValue?: number;
|
||||
hasConfig: boolean;
|
||||
}
|
||||
|
||||
interface StudyContextState {
|
||||
// Current selection
|
||||
currentStudy: Study | null;
|
||||
isCreatingNew: boolean;
|
||||
pendingStudyName: string | null;
|
||||
|
||||
// Actions
|
||||
selectStudy: (studyPath: string) => Promise<void>;
|
||||
createNewStudy: (name: string, category: string) => Promise<Study>;
|
||||
closeStudy: () => void;
|
||||
refreshStudies: () => Promise<void>;
|
||||
|
||||
// All studies
|
||||
studies: Study[];
|
||||
categories: string[];
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Canvas Store Enhancement
|
||||
|
||||
```typescript
|
||||
// hooks/useCanvasStore.ts additions
|
||||
|
||||
interface CanvasState {
|
||||
// Existing...
|
||||
nodes: Node[];
|
||||
edges: Edge[];
|
||||
|
||||
// New: Study context
|
||||
sourceStudyPath: string | null; // Where loaded from (null = new)
|
||||
isModified: boolean; // Has unsaved changes
|
||||
|
||||
// Actions
|
||||
loadFromStudy: (studyPath: string) => Promise<void>;
|
||||
saveToStudy: (studyPath: string, overwrite: boolean) => Promise<void>;
|
||||
markClean: () => void;
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Backend API Additions
|
||||
|
||||
```python
|
||||
# api/routes/studies.py
|
||||
|
||||
@router.post("/")
|
||||
async def create_study(request: CreateStudyRequest):
|
||||
"""Create new study folder structure."""
|
||||
# Creates:
|
||||
# studies/{category}/{name}/
|
||||
# ├── 1_config/
|
||||
# ├── 2_iterations/
|
||||
# └── 3_results/
|
||||
pass
|
||||
|
||||
@router.post("/{study_path}/copy-models")
|
||||
async def copy_model_files(study_path: str, source_study: str):
|
||||
"""Copy .prt, .sim, .fem files from another study."""
|
||||
pass
|
||||
|
||||
@router.post("/{study_path}/generate")
|
||||
async def generate_from_intent(study_path: str, intent: dict, overwrite: bool = False):
|
||||
"""Generate optimization_config.json and run_optimization.py from canvas intent."""
|
||||
pass
|
||||
|
||||
@router.get("/categories")
|
||||
async def list_categories():
|
||||
"""List all study categories."""
|
||||
pass
|
||||
```
|
||||
|
||||
### 4. File Structure
|
||||
|
||||
When a new study is created:
|
||||
|
||||
```
|
||||
studies/
|
||||
└── Bracket/
|
||||
└── my_new_bracket/
|
||||
├── 1_config/
|
||||
│ └── (empty until "Process")
|
||||
├── 2_iterations/
|
||||
│ └── (empty until optimization runs)
|
||||
└── 3_results/
|
||||
└── (empty until optimization runs)
|
||||
```
|
||||
|
||||
After "Process with Claude":
|
||||
|
||||
```
|
||||
studies/
|
||||
└── Bracket/
|
||||
└── my_new_bracket/
|
||||
├── 1_config/
|
||||
│ ├── optimization_config.json ← Generated
|
||||
│ └── workflow_config.json ← Generated (optional)
|
||||
├── 2_iterations/
|
||||
├── 3_results/
|
||||
├── model.prt ← Copied from source
|
||||
├── model_sim1.sim ← Copied from source
|
||||
└── run_optimization.py ← Generated
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Workflow Summary
|
||||
|
||||
### Starting Points
|
||||
|
||||
| Entry Point | Context | Canvas Mode |
|
||||
|-------------|---------|-------------|
|
||||
| Home → Click study → Canvas | Existing study | Edit existing |
|
||||
| Home → New Study → Blank | New study | Create new |
|
||||
| Home → New Study → Template | New study | Create new (pre-filled) |
|
||||
| Home → New Study → Copy from | New study | Create new (pre-filled) |
|
||||
|
||||
### Process Outcomes
|
||||
|
||||
| Canvas Mode | Process Choice | Result |
|
||||
|-------------|----------------|--------|
|
||||
| Edit existing | Update current | Overwrites config in same study |
|
||||
| Edit existing | Create new | Creates new study, switches to it |
|
||||
| Create new | (only option) | Creates files in new study |
|
||||
|
||||
### Post-Process Navigation
|
||||
|
||||
| Option | Action |
|
||||
|--------|--------|
|
||||
| Open Dashboard | Navigate to /dashboard with new study |
|
||||
| Run Optimization | Start run_optimization.py, show Dashboard |
|
||||
| Stay in Canvas | Keep editing (for iterations) |
|
||||
|
||||
---
|
||||
|
||||
## Benefits
|
||||
|
||||
1. **Clear mental model**: Users always know if they're editing or creating
|
||||
2. **No accidental overwrites**: Explicit choice with warning
|
||||
3. **Version control friendly**: Easy to create v2, v3, etc.
|
||||
4. **Discoverable**: Home page shows all studies at a glance
|
||||
5. **Flexible entry points**: Multiple ways to start/continue work
|
||||
|
||||
---
|
||||
|
||||
## Implementation Priority
|
||||
|
||||
1. **Home Page redesign** with study list and "New Study" button
|
||||
2. **Study context** global state
|
||||
3. **Create Study dialog** with options
|
||||
4. **Process dialog** with update/create choice
|
||||
5. **Canvas context awareness** (header shows current study)
|
||||
6. **Backend endpoints** for study creation and file generation
|
||||
|
||||
---
|
||||
|
||||
*This design enables a clean, intuitive workflow from study discovery to optimization execution.*
|
||||
Reference in New Issue
Block a user