Atomizer/docs/guides/DASHBOARD.md

Atomizer Dashboard

Last Updated: January 17, 2026 Version: 3.1 (AtomizerSpec v2.0)

---

Overview

The Atomizer Dashboard is a real-time web-based interface for monitoring and analyzing multi-objective optimization studies. Built with React, TypeScript, and Tailwind CSS, it provides comprehensive visualization and interaction capabilities for NSGA-II based structural optimization.

New in V3.1: All studies now use AtomizerSpec v2.0 as the unified configuration format. The atomizer_spec.json file serves as the single source of truth for Canvas, Backend, Claude, and the Optimization Engine.

Major Features

Feature	Route	Description
Canvas Builder	/canvas	Visual node-based workflow designer (AtomizerSpec v2.0)
Live Dashboard	/dashboard	Real-time optimization monitoring
Results Viewer	/results	Markdown reports with charts
Analytics	/analytics	Cross-study comparison
Claude Chat	Global	AI-powered study creation with spec tools

New in V3.1: The Canvas Builder now uses AtomizerSpec v2.0 as the unified configuration format, with support for custom extractors and real-time WebSocket synchronization.

---

Architecture

Frontend Stack

• Framework: React 18 with TypeScript
• Build Tool: Vite
• Styling: Tailwind CSS with custom dark/light theme support
• Charts: Recharts for data visualization
• State Management: React hooks (useState, useEffect)
• WebSocket: Real-time optimization updates

Backend Stack

• Framework: FastAPI (Python)
• Database: Optuna SQLite studies
• API: RESTful endpoints with WebSocket support
• CORS: Configured for local development

Ports

• Frontend: http://localhost:3003 (Vite dev server)
• Backend: http://localhost:8000 (FastAPI/Uvicorn)

---

Key Features

1. Multi-Objective Visualization

Pareto Front Plot

• 2D scatter plot showing trade-offs between objectives
• Color-coded by constraint satisfaction (green = feasible, red = infeasible)
• Interactive hover tooltips with trial details
• Automatically extracts Pareto-optimal solutions using NSGA-II

Parallel Coordinates Plot

Research-Based Multi-Dimensional Visualization

Structure: Design Variables → Objectives → Constraints

Features:

• Light Theme: White background with high-visibility dark text and colors
• Color-Coded Axes:
  • Blue background: Design variables
  • Green background: Objectives
  • Yellow background: Constraints
• Interactive Selection:
  • Hover over lines to highlight individual trials
  • Click to select/deselect trials
  • Multi-select with visual feedback (orange highlight)
• Type Badges: Labels showing DESIGN VAR, OBJECTIVE, or CONSTRAINT
• Units Display: Automatic unit labeling (mm, MPa, Hz, g, etc.)
• Min/Max Labels: Range values displayed on each axis
• Feasibility Coloring:
  • Green: Feasible solutions
  • Red: Infeasible solutions (constraint violations)
  • Blue: Hover highlight
  • Orange: Selected trials

Implementation: ParallelCoordinatesPlot.tsx

Line colors:

if (isSelected) return '#FF6B00';      // Orange for selected
if (!trial.feasible) return '#DC2626'; // Red for infeasible
if (isHovered) return '#2563EB';       // Blue for hover
return '#10B981';                       // Green for feasible

2. Optimizer Strategy Panel

Displays algorithm information:

• Algorithm: NSGA-II, TPE, or custom
• Type: Single-objective or Multi-objective
• Objectives Count: Number of optimization objectives
• Design Variables Count: Number of design parameters

3. Convergence Plot (Enhanced)

File: atomizer-dashboard/frontend/src/components/ConvergencePlot.tsx

Advanced convergence visualization:

• Dual-line plot: Individual trial values + running best trajectory
• Area fill: Gradient under trial values curve
• Statistics panel: Best value, improvement %, 90% convergence trial
• Summary footer: First value, mean, std dev, total trials
• Step-after interpolation: Running best shown as step function

4. Parameter Importance Chart

File: atomizer-dashboard/frontend/src/components/ParameterImportanceChart.tsx

Correlation-based parameter analysis:

• Pearson correlation: Calculates correlation between each parameter and objective
• Horizontal bar chart: Parameters ranked by absolute importance
• Color coding: Green (negative correlation - helps minimize), Red (positive - hurts minimize)
• Tooltip: Shows percentage importance and raw correlation coefficient (r)
• Minimum 3 trials: Required for statistical significance

5. Study Report Viewer

File: atomizer-dashboard/frontend/src/components/StudyReportViewer.tsx

Full-featured markdown report viewer:

• Modal overlay: Full-screen report viewing
• Math equations: KaTeX support for LaTeX math ($...$ inline, $$...$$ block)
• GitHub-flavored markdown: Tables, code blocks, task lists
• Custom styling: Dark theme with proper typography
• Syntax highlighting: Code blocks with language detection
• Refresh button: Re-fetch report for live updates
• External link: Open in system editor

6. Trial History Table

• Comprehensive list of all trials
• Sortable columns
• Status indicators (COMPLETE, PRUNED, FAIL)
• Parameter values and objective values
• User attributes (constraints)

7. Pruned Trials Tracking

• Real-time count: Fetched directly from Optuna database
• Pruning diagnostics: Tracks pruned trial params and causes
• Database query: Uses SQLite state = 'PRUNED' filter

8. Analytics Page (Cross-Study Comparisons)

File: atomizer-dashboard/frontend/src/pages/Analytics.tsx

Dedicated analytics page for comparing optimization studies:

Aggregate Statistics

• Total Studies: Count of all studies in the system
• Running/Paused/Completed: Status distribution breakdown
• Total Trials: Sum of trials across all studies
• Avg Trials/Study: Average trial count per study
• Best Overall: Best objective value across all studies with study ID

Study Comparison Table

• Sortable columns: Name, Status, Progress, Best Value
• Status indicators: Color-coded badges (running=green, paused=orange, completed=blue)
• Progress bars: Visual completion percentage with color coding
• Quick actions: Open button to navigate directly to a study's dashboard
• Selected highlight: Current study highlighted with "Selected" badge
• Click-to-expand: Row expansion for additional details

Status Distribution Chart

• Visual breakdown of studies by status
• Horizontal bar chart with percentage fill
• Color-coded: Running (green), Paused (orange), Completed (blue), Not Started (gray)

Top Performers Panel

• Ranking of top 5 studies by best objective value (assumes minimization)
• Medal-style numbering (gold, silver, bronze for top 3)
• Clickable rows to navigate to study
• Trial count display

Usage: Navigate to /analytics when a study is selected. Provides aggregate view across all studies.

9. Global Claude Terminal

Files:

• atomizer-dashboard/frontend/src/components/GlobalClaudeTerminal.tsx
• atomizer-dashboard/frontend/src/components/ClaudeTerminal.tsx
• atomizer-dashboard/frontend/src/context/ClaudeTerminalContext.tsx

Persistent AI assistant terminal:

• Global persistence: Terminal persists across page navigation
• WebSocket connection: Real-time communication with Claude Code backend
• Context awareness: Automatically includes current study context when available
• New Study mode: When no study selected, offers guided study creation wizard
• Visual indicators: Connection status shown in sidebar footer
• Keyboard shortcut: Open/close terminal from anywhere

Modes:

• With Study Selected: "Set Context" button loads study-specific context
• No Study Selected: "New Study" button starts guided wizard from .claude/skills/guided-study-wizard.md

10. Shared Markdown Renderer

File: atomizer-dashboard/frontend/src/components/MarkdownRenderer.tsx

Reusable markdown rendering component:

• Syntax highlighting: Prism-based code highlighting with oneDark theme
• GitHub-flavored markdown: Tables, task lists, strikethrough
• LaTeX math support: KaTeX rendering with remark-math and rehype-katex
• Custom styling: Dark theme typography optimized for dashboard
• Used by: Home page (README display), Results page (reports)

---

Pages Structure

Home Page (/)

• Study navigator and selector
• README.md display with full markdown rendering
• New study creation via Claude terminal

Canvas Page (/canvas) NEW

• Visual node-based workflow builder
• Drag-and-drop node palette with 8 node types
• Claude integration for workflow processing
• Auto-load from existing studies
• Expression search for design variables
• See Canvas Documentation for details

Dashboard Page (/dashboard)

• Real-time live tracker for selected study
• Convergence plot, Pareto front, parameter importance
• Trial history table

Reports Page (/results)

• AI-generated optimization report viewer
• Full markdown rendering with syntax highlighting and math
• Copy and download capabilities

Analytics Page (/analytics)

• Cross-study comparison and aggregate statistics
• Study ranking and status distribution
• Quick navigation to individual studies

---

API Endpoints

AtomizerSpec (V3.1)

GET /api/studies/{study_id}/spec

Get the full AtomizerSpec for a study.

Response:

{
  "meta": { "version": "2.0", "study_name": "..." },
  "model": { "sim": { "path": "...", "solver": "nastran" } },
  "design_variables": [...],
  "extractors": [...],
  "objectives": [...],
  "constraints": [...],
  "optimization": { "algorithm": { "type": "TPE" }, "budget": { "max_trials": 100 } },
  "canvas": { "edges": [...], "layout_version": "2.0" }
}

PUT /api/studies/{study_id}/spec

Replace the entire spec with validation.

PATCH /api/studies/{study_id}/spec

Partial update using JSONPath. Body: { "path": "design_variables[0].bounds.max", "value": 15.0 }

POST /api/studies/{study_id}/spec/validate

Validate spec and return detailed report. Returns: { "valid": true, "errors": [], "warnings": [] }

POST /api/studies/{study_id}/spec/nodes

Add a new node (design variable, extractor, objective, constraint).

PATCH /api/studies/{study_id}/spec/nodes/{node_id}

Update an existing node's properties.

DELETE /api/studies/{study_id}/spec/nodes/{node_id}

Remove a node and clean up related edges.

Studies

GET /api/optimization/studies

List all available optimization studies.

Response:

[
  {
    "id": "drone_gimbal_arm_optimization",
    "name": "drone_gimbal_arm_optimization",
    "direction": ["minimize", "maximize"],
    "n_trials": 100,
    "best_value": [3245.67, 165.3],
    "sampler": "NSGAIISampler"
  }
]

GET /api/optimization/studies/{study_id}/trials

Get all trials for a study.

Response:

{
  "trials": [
    {
      "number": 0,
      "values": [3456.2, 145.6],
      "params": {
        "beam_half_core_thickness": 7.5,
        "beam_face_thickness": 2.1,
        "holes_diameter": 30.0,
        "hole_count": 11
      },
      "state": "COMPLETE",
      "user_attrs": {
        "max_stress": 95.3,
        "max_displacement": 1.2,
        "frequency": 145.6,
        "mass": 3456.2,
        "constraint_satisfied": true
      }
    }
  ]
}

GET /api/optimization/studies/{study_id}/metadata

Get study metadata including objectives and design variables.

Response:

{
  "objectives": [
    {
      "name": "mass",
      "type": "minimize",
      "unit": "g"
    },
    {
      "name": "frequency",
      "type": "maximize",
      "unit": "Hz"
    }
  ],
  "design_variables": [
    {
      "name": "beam_half_core_thickness",
      "unit": "mm",
      "min": 5.0,
      "max": 10.0
    }
  ],
  "sampler": "NSGAIISampler"
}

GET /api/optimization/studies/{study_id}/pareto-front

Get Pareto-optimal solutions for multi-objective studies.

Response:

{
  "is_multi_objective": true,
  "pareto_front": [
    {
      "trial_number": 0,
      "values": [3245.67, 165.3],
      "params": {...},
      "user_attrs": {...},
      "constraint_satisfied": true
    }
  ]
}

WebSocket

WS /ws/optimization/{study_id}

Real-time trial updates during optimization.

Message Format:

{
  "type": "trial_complete",
  "trial": {
    "number": 5,
    "values": [3456.2, 145.6],
    "params": {...}
  }
}

---

Running the Dashboard

Backend

cd atomizer-dashboard/backend
python -m uvicorn api.main:app --reload --port 8000

Frontend

cd atomizer-dashboard/frontend
npm run dev

Access at: http://localhost:3003

---

Configuration

Vite Proxy (vite.config.ts)

export default defineConfig({
  plugins: [react()],
  server: {
    host: '0.0.0.0',
    port: 3003,
    proxy: {
      '/api': {
        target: 'http://127.0.0.1:8000',
        changeOrigin: true,
        secure: false,
        ws: true,  // WebSocket support
      }
    }
  }
})

CORS (backend/api/main.py)

app.add_middleware(
    CORSMiddleware,
    allow_origins=["http://localhost:3003"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

---

Component Structure

atomizer-dashboard/
├── frontend/
│   ├── src/
│   │   ├── components/
│   │   │   ├── canvas/                          # Canvas Builder V2
│   │   │   │   ├── AtomizerCanvas.tsx           # Main canvas with React Flow
│   │   │   │   ├── nodes/                       # 8 node type components
│   │   │   │   │   ├── BaseNode.tsx             # Base with Lucide icons
│   │   │   │   │   ├── ModelNode.tsx            # Cube icon
│   │   │   │   │   ├── SolverNode.tsx           # Cpu icon
│   │   │   │   │   ├── DesignVarNode.tsx        # SlidersHorizontal icon
│   │   │   │   │   ├── ExtractorNode.tsx        # FlaskConical icon
│   │   │   │   │   ├── ObjectiveNode.tsx        # Target icon
│   │   │   │   │   ├── ConstraintNode.tsx       # ShieldAlert icon
│   │   │   │   │   ├── AlgorithmNode.tsx        # BrainCircuit icon
│   │   │   │   │   └── SurrogateNode.tsx        # Rocket icon
│   │   │   │   ├── panels/
│   │   │   │   │   ├── NodeConfigPanel.tsx      # Config sidebar
│   │   │   │   │   ├── ValidationPanel.tsx      # Validation toast
│   │   │   │   │   ├── ChatPanel.tsx            # Claude chat
│   │   │   │   │   ├── ConfigImporter.tsx       # Study browser
│   │   │   │   │   └── TemplateSelector.tsx     # Workflow templates
│   │   │   │   └── palette/
│   │   │   │       └── NodePalette.tsx          # Draggable palette
│   │   │   ├── chat/                            # Chat components
│   │   │   │   ├── ChatMessage.tsx              # Message display
│   │   │   │   └── ThinkingIndicator.tsx        # Loading indicator
│   │   │   ├── ParallelCoordinatesPlot.tsx      # Multi-objective viz
│   │   │   ├── ParetoPlot.tsx                   # Pareto front scatter
│   │   │   ├── OptimizerPanel.tsx               # Strategy info
│   │   │   ├── ConvergencePlot.tsx              # Convergence chart
│   │   │   ├── ParameterImportanceChart.tsx     # Parameter importance
│   │   │   ├── StudyReportViewer.tsx            # Report viewer
│   │   │   ├── MarkdownRenderer.tsx             # Markdown renderer
│   │   │   ├── ClaudeTerminal.tsx               # Claude terminal
│   │   │   ├── GlobalClaudeTerminal.tsx         # Global terminal
│   │   │   ├── common/
│   │   │   │   ├── Card.tsx                     # Card component
│   │   │   │   └── Button.tsx                   # Button component
│   │   │   ├── layout/
│   │   │   │   ├── Sidebar.tsx                  # Navigation
│   │   │   │   └── MainLayout.tsx               # Layout wrapper
│   │   │   └── dashboard/
│   │   │       ├── MetricCard.tsx               # KPI display
│   │   │       └── StudyCard.tsx                # Study selector
│   │   ├── pages/
│   │   │   ├── Home.tsx                         # Study selection
│   │   │   ├── CanvasView.tsx                   # Canvas builder
│   │   │   ├── Dashboard.tsx                    # Live tracker
│   │   │   ├── Results.tsx                      # Report viewer
│   │   │   └── Analytics.tsx                    # Analytics
│   │   ├── hooks/
│   │   │   ├── useCanvasStore.ts                # Zustand canvas state
│   │   │   ├── useCanvasChat.ts                 # Canvas chat
│   │   │   ├── useChat.ts                       # WebSocket chat
│   │   │   └── useWebSocket.ts                  # WebSocket base
│   │   ├── lib/canvas/
│   │   │   ├── schema.ts                        # Type definitions
│   │   │   ├── intent.ts                        # Intent serialization
│   │   │   ├── validation.ts                    # Graph validation
│   │   │   └── templates.ts                     # Workflow templates
│   │   ├── context/
│   │   │   ├── StudyContext.tsx                 # Study state
│   │   │   └── ClaudeTerminalContext.tsx        # Terminal state
│   │   ├── api/
│   │   │   └── client.ts                        # API client
│   │   └── types/
│   │       └── index.ts                         # TypeScript types
│   └── vite.config.ts
├── backend/
│   └── api/
│       ├── main.py                              # FastAPI app
│       ├── services/
│       │   ├── claude_agent.py                  # Claude API integration
│       │   ├── session_manager.py               # Session lifecycle
│       │   ├── context_builder.py               # Context assembly
│       │   └── conversation_store.py            # SQLite persistence
│       └── routes/
│           ├── optimization.py                  # Optimization endpoints
│           ├── studies.py                       # Study config endpoints
│           ├── nx.py                            # NX introspection
│           └── terminal.py                      # Claude WebSocket
└── mcp-server/atomizer-tools/
    └── src/
        ├── index.ts                             # MCP server entry
        └── tools/
            ├── canvas.ts                        # Canvas tools
            ├── study.ts                         # Study management
            ├── optimization.ts                  # Optimization control
            └── analysis.ts                      # Analysis tools

NPM Dependencies

The frontend uses these key packages:

• react-markdown - Markdown rendering
• remark-gfm - GitHub-flavored markdown support
• remark-math - Math equation parsing
• rehype-katex - KaTeX math rendering
• recharts - Interactive charts

---

Data Flow

1. Optimization Engine runs trials and stores results in Optuna SQLite database
2. Backend API reads from database and exposes REST endpoints
3. Frontend fetches data via /api/optimization/* endpoints
4. WebSocket pushes real-time updates to connected clients
5. React Components render visualizations based on fetched data

---

Troubleshooting

Dashboard Page Crashes

Issue: TypeError: Cannot read properties of undefined (reading 'split')

Fix: Ensure all data is validated before rendering. ParallelCoordinatesPlot now includes:

if (!paretoData || paretoData.length === 0) return <EmptyState />;
if (!objectives || !designVariables) return <EmptyState />;

No Data Showing

1. Check backend is running: curl http://localhost:8000/api/optimization/studies
2. Verify study exists in Optuna database
3. Check browser console for API errors
4. Ensure WebSocket connection is established

CORS Errors

• Backend must allow origin http://localhost:3003
• Frontend proxy must target http://127.0.0.1:8000 (not localhost)

---

Best Practices

For Multi-Objective Studies

1. Always use metadata endpoint to get objective/variable definitions
2. Extract constraints from user_attrs for parallel coordinates
3. Filter Pareto front using paretoData.pareto_front array
4. Validate constraint_satisfied field before coloring

For Real-Time Updates

1. Use WebSocket for live trial updates
2. Debounce state updates to avoid excessive re-renders
3. Close WebSocket connection on component unmount

For Performance

1. Limit displayed trials for large studies (e.g., show last 1000)
2. Use React.memo for expensive components
3. Virtualize large lists if showing >100 trials in tables

---

Recent Updates

January 2026 (V3.1) - AtomizerSpec v2.0

• AtomizerSpec v2.0: Unified configuration architecture

  • Single Source of Truth: One atomizer_spec.json file for Canvas, Backend, Claude, and Optimization Engine
  • Spec REST API: Full CRUD operations at /api/studies/{id}/spec
  • Pydantic Validation: Backend validation with detailed error messages
  • Legacy Migration: Automatic migration from optimization_config.json
  • 29 Studies Migrated: All existing studies converted to v2.0 format

• Custom Extractors: Define custom Python extraction functions in the spec

  • Security Validation: Code checked for dangerous patterns
  • Runtime Loading: Functions executed during optimization
  • Canvas UI: Code editor panel for custom extractor nodes

• WebSocket Sync: Real-time spec synchronization

  • Multiple clients stay synchronized
  • Optimistic updates with rollback on error
  • Conflict detection with hash comparison

• Comprehensive Testing: Full test coverage for Phase 4

  • Unit tests for SpecManager and Pydantic models
  • API integration tests for all spec endpoints
  • Migration tests for legacy config formats
  • E2E tests for complete workflow

January 2026 (V3.0)

• Canvas Builder V3: Major upgrade with model introspection and Claude fixes

  • File Browser: Browse studies directory for .sim/.prt/.fem/.afem files
  • Model Introspection: Auto-discover expressions, solver type, and dependencies
  • One-Click Add: Add expressions as design variables, add suggested extractors
  • Claude Bug Fixes: Fixed SQL errors, WebSocket reconnection, chat integration
  • Connection Flow Fix: Design variables now correctly flow INTO model nodes
  • Health Check Endpoint: /api/health for database status monitoring

• Canvas Builder V2: Complete visual workflow designer with React Flow

  • 8 node types with professional Lucide icons
  • Drag-and-drop node palette
  • Expression search dropdown for design variables
  • Auto-load from existing optimization_config.json
  • "Process with Claude" button for AI-assisted study creation
  • MCP canvas tools (validate, execute, interpret)
  • Responsive full-screen layout

• Backend Services:

  • NX introspection service (/api/nx/introspect, /api/nx/expressions)
  • File browser API (/api/files/list)
  • Claude session management with SQLite persistence
  • Context builder for study-aware conversations

• Optimization Engine v2.0: Major code reorganization

  • New modular structure: core/, nx/, study/, config/, reporting/, processors/
  • Backwards-compatible imports with deprecation warnings
  • 120 files reorganized for better maintainability

December 2025

• Convergence Plot: Enhanced with running best, statistics, and gradient fill
• Parameter Importance Chart: Correlation analysis with color-coded bars
• Study Report Viewer: Full markdown rendering with KaTeX math support
• Pruned Trials: Real-time count from Optuna database (not JSON file)
• Chart Data Transformation: Fixed values array mapping for single/multi-objective
• Analytics Page: Dedicated cross-study comparison and aggregate statistics view
• Global Claude Terminal: Persistent AI terminal with study context awareness
• Shared Markdown Renderer: Reusable component with syntax highlighting and math support
• Study Session Persistence: localStorage-based study selection that survives page refresh
• Paused Status Support: Full support for paused optimization status throughout UI
• Guided Study Wizard: Interactive wizard skill for creating new studies via Claude

Future Enhancements

• 3D Pareto front visualization for 3+ objectives
• Advanced filtering and search in trial history
• Export results to CSV/JSON
• Custom parallel coordinates brushing/filtering
• Hypervolume indicator tracking
• Interactive design variable sliders
• Constraint importance analysis
• Tauri desktop application (Phase 5)

---

References

• Optuna Documentation: https://optuna.readthedocs.io/
• NSGA-II Algorithm: Deb et al. (2002)
• Parallel Coordinates: Inselberg & Dimsdale (1990)
• React Documentation: https://react.dev/
• FastAPI Documentation: https://fastapi.tiangolo.com/