# 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; createNewStudy: (name: string, category: string) => Promise; closeStudy: () => void; refreshStudies: () => Promise; // 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; saveToStudy: (studyPath: string, overwrite: boolean) => Promise; 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.*