Anto01
1c7c7aff05
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>
453 lines
22 KiB
Markdown
453 lines
22 KiB
Markdown
# 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.*
|