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>
22 KiB
22 KiB
Canvas UX Design - Study Management Flow
Created: January 16, 2026 Status: Design Phase
Problem Statement
The Canvas Builder needs clear answers to these questions:
- When processing a canvas, does it overwrite the current study or create a new one?
- How do users start fresh - create a new study from scratch?
- How does the Home page handle study selection vs. creation?
- 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
// 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
// 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
# 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
- Clear mental model: Users always know if they're editing or creating
- No accidental overwrites: Explicit choice with warning
- Version control friendly: Easy to create v2, v3, etc.
- Discoverable: Home page shows all studies at a glance
- Flexible entry points: Multiple ways to start/continue work
Implementation Priority
- Home Page redesign with study list and "New Study" button
- Study context global state
- Create Study dialog with options
- Process dialog with update/create choice
- Canvas context awareness (header shows current study)
- Backend endpoints for study creation and file generation
This design enables a clean, intuitive workflow from study discovery to optimization execution.