# Atomizer Dashboard - Master Plan

**Version**: 1.0
**Date**: November 21, 2025
**Status**: Planning Phase

---

## Executive Summary

A modern, real-time web dashboard for Atomizer that provides:
1. **Study Configurator** - Interactive UI + LLM chat interface for study setup
2. **Live Dashboard** - Real-time optimization monitoring with charts/graphs
3. **Results Viewer** - Rich markdown report display with interactive visualizations

---

## Architecture Overview

### Tech Stack Recommendation

#### Backend
- **FastAPI** - Modern Python web framework
  - Native async support for real-time updates
  - Automatic OpenAPI documentation
  - WebSocket support for live streaming
  - Easy integration with existing Python codebase

#### Frontend
- **React** - Component-based UI framework
  - **Vite** - Fast development and build tool
  - **TailwindCSS** - Utility-first styling
  - **Recharts** - React charting library
  - **React Markdown** - Markdown rendering with code highlighting
  - **Socket.IO** (or native WebSocket) - Real-time communication

#### State Management
- **React Query (TanStack Query)** - Server state management
  - Automatic caching and refetching
  - Real-time updates
  - Optimistic updates

#### Database (Optional Enhancement)
- **SQLite** (already using via Optuna) - Study metadata
- File-based JSON for real-time data (current approach works well)

---

## Application Structure

```
atomizer-dashboard/
├── backend/
│   ├── api/
│   │   ├── main.py                    # FastAPI app entry
│   │   ├── routes/
│   │   │   ├── studies.py             # Study CRUD operations
│   │   │   ├── optimization.py        # Start/stop/monitor optimization
│   │   │   ├── llm.py                 # LLM chat interface
│   │   │   └── reports.py             # Report generation/viewing
│   │   ├── websocket/
│   │   │   └── optimization_stream.py # Real-time optimization updates
│   │   └── services/
│   │       ├── study_service.py       # Study management logic
│   │       ├── optimization_service.py # Optimization runner
│   │       └── llm_service.py         # LLM integration
│   └── requirements.txt
│
├── frontend/
│   ├── src/
│   │   ├── pages/
│   │   │   ├── Configurator.tsx       # Study configuration page
│   │   │   ├── Dashboard.tsx          # Live optimization dashboard
│   │   │   └── Results.tsx            # Results viewer
│   │   ├── components/
│   │   │   ├── StudyForm.tsx          # Manual study configuration
│   │   │   ├── LLMChat.tsx            # Chat interface with Claude
│   │   │   ├── LiveCharts.tsx         # Real-time optimization charts
│   │   │   ├── MarkdownReport.tsx     # Markdown report renderer
│   │   │   └── ParameterTable.tsx     # Design variables table
│   │   ├── hooks/
│   │   │   ├── useStudies.ts          # Study data fetching
│   │   │   ├── useOptimization.ts     # Optimization control
│   │   │   └── useWebSocket.ts        # WebSocket connection
│   │   └── App.tsx
│   └── package.json
│
└── docs/
    └── DASHBOARD_MASTER_PLAN.md (this file)
```

---

## Page 1: Study Configurator

### Purpose
Create and configure new optimization studies through:
- Manual form-based configuration
- LLM-assisted natural language setup (future)

### Layout

```
┌─────────────────────────────────────────────────────────────┐
│  Atomizer - Study Configurator                 [Home] [Help]│
├─────────────────────────────────────────────────────────────┤
│                                                               │
│  ┌─────────────────────┬─────────────────────────────────┐  │
│  │   Study Setup       │   LLM Assistant (Future)        │  │
│  │                     │   ┌───────────────────────────┐ │  │
│  │  Study Name:        │   │ Chat with Claude Code     │ │  │
│  │  [____________]     │   │                           │ │  │
│  │                     │   │ > "Create a study to      │ │  │
│  │  Model Files:       │   │    tune circular plate    │ │  │
│  │  [Browse .prt]      │   │    to 115 Hz"             │ │  │
│  │  [Browse .sim]      │   │                           │ │  │
│  │                     │   │ Claude: "I'll configure   │ │  │
│  │  Design Variables:  │   │ the study for you..."     │ │  │
│  │  + Add Variable     │   │                           │ │  │
│  │   • diameter        │   │ [Type message...]         │ │  │
│  │     [50-150] mm     │   └───────────────────────────┘ │  │
│  │   • thickness       │                                 │  │
│  │     [2-10] mm       │   Generated Configuration:      │  │
│  │                     │   ┌───────────────────────────┐ │  │
│  │  Optimization Goal: │   │ • Study: freq_tuning      │ │  │
│  │  [Minimize ▼]       │   │ • Target: 115.0 Hz        │ │  │
│  │                     │   │ • Variables: 2            │ │  │
│  │  Target Value:      │   │ • Trials: 50              │ │  │
│  │  [115.0] Hz         │   │                           │ │  │
│  │  Tolerance: [0.1]   │   │ [Apply Configuration]     │ │  │
│  │                     │   └───────────────────────────┘ │  │
│  │  [Advanced Options] │                                 │  │
│  │                     │                                 │  │
│  │  [Create Study]     │                                 │  │
│  └─────────────────────┴─────────────────────────────────┘  │
│                                                               │
│  Recent Studies                                               │
│  ┌───────────────────────────────────────────────────────┐  │
│  │ • circular_plate_frequency_tuning    [View] [Resume]  │  │
│  │ • beam_deflection_minimization       [View] [Resume]  │  │
│  └───────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
```

### Features

#### Manual Configuration
- **Study metadata**: Name, description, tags
- **Model upload**: .prt, .sim, .fem files (drag-and-drop)
- **Design variables**:
  - Add/remove parameters
  - Set bounds (min, max, step)
  - Units specification
- **Objective function**:
  - Goal type (minimize, maximize, target)
  - Target value + tolerance
  - Multi-objective support (future)
- **Optimization settings**:
  - Number of trials
  - Sampler selection (TPE, CMA-ES, Random)
  - Early stopping rules
- **Validation rules**: Optional constraints

#### LLM Assistant (Future Phase)
- **Chat interface**: Embedded terminal-like chat with Claude Code
  - Natural language study configuration
  - Example: "Create a study to tune the first natural frequency of a circular plate to exactly 115 Hz"
- **Real-time configuration generation**:
  - LLM parses intent
  - Generates `workflow_config.json` and `optimization_config.json`
  - Shows preview of generated config
  - User can review and approve
- **Iterative refinement**:
  - User: "Change target to 120 Hz"
  - User: "Add thickness constraint < 8mm"
- **Context awareness**: LLM has access to:
  - Uploaded model files
  - Available extractors
  - Previous studies
  - PROTOCOL.md guidelines

### API Endpoints

```python
# backend/api/routes/studies.py

@router.post("/studies")
async def create_study(study_config: StudyConfig):
    """Create new study from configuration"""

@router.get("/studies")
async def list_studies():
    """List all studies with metadata"""

@router.get("/studies/{study_id}")
async def get_study(study_id: str):
    """Get study details"""

@router.put("/studies/{study_id}")
async def update_study(study_id: str, config: StudyConfig):
    """Update study configuration"""

@router.delete("/studies/{study_id}")
async def delete_study(study_id: str):
    """Delete study"""
```

```python
# backend/api/routes/llm.py (Future)

@router.post("/llm/chat")
async def chat_with_llm(message: str, context: dict):
    """Send message to Claude Code, get response + generated config"""

@router.post("/llm/apply-config")
async def apply_llm_config(study_id: str, generated_config: dict):
    """Apply LLM-generated configuration to study"""
```

---

## Page 2: Live Optimization Dashboard

### Purpose
Monitor running optimizations in real-time with interactive visualizations.

### Layout

```
┌─────────────────────────────────────────────────────────────┐
│  Atomizer - Live Dashboard              [Configurator] [Help]│
├─────────────────────────────────────────────────────────────┤
│  Study: circular_plate_frequency_tuning         [Stop] [Pause]│
│  Status: RUNNING    Progress: 23/50 trials (46%)             │
│  Best: 0.185 Hz    Time: 15m 32s    ETA: 18m                 │
├─────────────────────────────────────────────────────────────┤
│                                                               │
│  ┌─────────────────────────────┬───────────────────────────┐ │
│  │   Convergence Plot          │   Parameter Space         │ │
│  │                             │                           │ │
│  │   Objective (Hz)            │   thickness               │ │
│  │   ↑                         │   ↑                       │ │
│  │ 5 │  •                      │ 10│                       │ │
│  │   │   •                     │   │    • •                │ │
│  │ 3 │    •  •                 │  8│  •  ⭐  •            │ │
│  │   │      • •                │   │ •  • •  •            │ │
│  │ 1 │        •••              │  6│   •  •               │ │
│  │   │          •⭐            │   │    •                  │ │
│  │ 0 └─────────────────→ Trial │  4│                       │ │
│  │      0   10   20   30       │   └──────────────→       │ │
│  │                             │     50     100   150      │ │
│  │  Target: 115.0 Hz ±0.1     │        diameter           │ │
│  │  Current Best: 115.185 Hz  │   ⭐ = Best trial         │ │
│  └─────────────────────────────┴───────────────────────────┘ │
│                                                               │
│  ┌─────────────────────────────┬───────────────────────────┐ │
│  │   Recent Trials             │   System Stats            │ │
│  │                             │                           │ │
│  │  #23  0.234 Hz  ✓           │   CPU: 45%                │ │
│  │  #22  1.456 Hz  ✓           │   Memory: 2.1 GB          │ │
│  │  #21  0.876 Hz  ✓           │   NX Sessions: 1          │ │
│  │  #20  0.185 Hz  ⭐ NEW BEST │   Solver Queue: 0         │ │
│  │  #19  2.345 Hz  ✓           │                           │ │
│  │  #18  PRUNED    ✗           │   Pruned: 3 (13%)         │ │
│  │                             │   Success: 20 (87%)       │ │
│  └─────────────────────────────┴───────────────────────────┘ │
│                                                               │
│  ┌───────────────────────────────────────────────────────┐  │
│  │   Strategy Performance (Protocol 10)                  │  │
│  │                                                       │  │
│  │   Phase: EXPLOITATION (CMA-ES)                       │  │
│  │   Transition at Trial #15 (confidence: 72%)          │  │
│  │                                                       │  │
│  │   TPE (Trials 1-15):    Best = 0.485 Hz             │  │
│  │   CMA-ES (Trials 16+):  Best = 0.185 Hz             │  │
│  │                                                       │  │
│  └───────────────────────────────────────────────────────┘  │
│                                                               │
│  [View Full Report] [Download Data] [Clone Study]            │
└─────────────────────────────────────────────────────────────┘
```

### Features

#### Real-Time Updates (WebSocket)
- **Trial completion**: Instant notification when trial finishes
- **Best value updates**: Highlight new best trials
- **Progress tracking**: Current trial number, elapsed time, ETA
- **Status changes**: Running → Paused → Completed

#### Interactive Charts
1. **Convergence Plot**
   - X-axis: Trial number
   - Y-axis: Objective value
   - Target line (if applicable)
   - Best value trajectory
   - Hover: Show trial details

2. **Parameter Space Visualization**
   - 2D scatter plot (for 2D problems)
   - 3D scatter plot (for 3D problems, using Three.js)
   - High-D: Parallel coordinates plot
   - Color-coded by objective value
   - Click trial → Show details popup

3. **Parameter Importance** (Protocol 9)
   - Bar chart from Optuna's fANOVA
   - Shows which parameters matter most
   - Updates after characterization phase

4. **Strategy Performance** (Protocol 10)
   - Timeline showing strategy switches
   - Performance comparison table
   - Confidence metrics over time

#### Trial Table
- Recent 10 trials (scrollable to see all)
- Columns: Trial #, Objective, Parameters, Status, Time
- Click row → Expand details:
  - Full parameter values
  - Simulation time
  - Solver logs (if failed)
  - Pruning reason (if pruned)

#### Control Panel
- **Stop**: Gracefully stop optimization
- **Pause**: Pause after current trial
- **Resume**: Continue optimization
- **Clone**: Create new study with same config

#### Pruning Diagnostics
- Real-time pruning alerts
- Pruning breakdown (validation, simulation, OP2)
- False positive detection warnings
- Link to detailed pruning log

### API Endpoints

```python
# backend/api/routes/optimization.py

@router.post("/studies/{study_id}/start")
async def start_optimization(study_id: str):
    """Start optimization (spawns background process)"""

@router.post("/studies/{study_id}/stop")
async def stop_optimization(study_id: str):
    """Stop optimization gracefully"""

@router.post("/studies/{study_id}/pause")
async def pause_optimization(study_id: str):
    """Pause after current trial"""

@router.get("/studies/{study_id}/status")
async def get_status(study_id: str):
    """Get current optimization status"""

@router.get("/studies/{study_id}/history")
async def get_history(study_id: str, limit: int = 100):
    """Get trial history (reads optimization_history_incremental.json)"""
```

```python
# backend/api/websocket/optimization_stream.py

@router.websocket("/ws/optimization/{study_id}")
async def optimization_stream(websocket: WebSocket, study_id: str):
    """
    WebSocket endpoint for real-time updates.

    Watches:
    - optimization_history_incremental.json (file watcher)
    - pruning_history.json
    - study.db (Optuna trial completion events)

    Sends:
    - trial_completed: { trial_number, objective, params, status }
    - new_best: { trial_number, objective }
    - status_change: { status: "running" | "paused" | "completed" }
    - progress_update: { current, total, eta }
    """
```

---

## Page 3: Results Viewer

### Purpose
Display completed optimization reports with rich markdown rendering and interactive visualizations.

### Layout

```
┌─────────────────────────────────────────────────────────────┐
│  Atomizer - Results                [Dashboard] [Configurator]│
├─────────────────────────────────────────────────────────────┤
│  Study: circular_plate_frequency_tuning                       │
│  Status: COMPLETED    Trials: 50/50    Time: 35m 12s         │
│  Best: 0.185 Hz (Trial #45)    Target: 115.0 Hz              │
├─────────────────────────────────────────────────────────────┤
│                                                               │
│  ┌────────────────┬──────────────────────────────────────┐  │
│  │  Navigation    │  Report Content                      │  │
│  │                │                                      │  │
│  │  • Summary     │  # Optimization Report               │  │
│  │  • Best Result │  **Study**: circular_plate_...       │  │
│  │  • All Trials  │                                      │  │
│  │  • Convergence │  ## Achieved Performance             │  │
│  │  • Parameters  │  - **First Frequency**: 115.185 Hz   │  │
│  │  • Strategy    │    - Target: 115.000 Hz              │  │
│  │  • Pruning     │    - Error: 0.185 Hz (0.16%)         │  │
│  │  • Downloads   │                                      │  │
│  │                │  ## Design Parameters                │  │
│  │  [Live View]   │  - **Inner Diameter**: 94.07 mm      │  │
│  │  [Refresh]     │  - **Plate Thickness**: 6.14 mm      │  │
│  │                │                                      │  │
│  │                │  ## Convergence Plot                 │  │
│  │                │  [Interactive Chart Embedded]        │  │
│  │                │                                      │  │
│  │                │  ## Top 10 Trials                    │  │
│  │                │  | Rank | Trial | Frequency | ...   │  │
│  │                │  |------|-------|-----------|------- │  │
│  │                │  | 1    | #45   | 115.185   | ...   │  │
│  │                │                                      │  │
│  └────────────────┴──────────────────────────────────────┘  │
│                                                               │
│  Actions:                                                     │
│  [Download Report (MD)] [Download Data (JSON)] [Download     │
│   Charts (PNG)] [Clone Study] [Continue Optimization]        │
└─────────────────────────────────────────────────────────────┘
```

### Features

#### Markdown Report Rendering
- **Rich formatting**: Headings, tables, lists, code blocks
- **Syntax highlighting**: For code snippets (using highlight.js)
- **LaTeX support** (future): For mathematical equations
- **Auto-linking**: File references → clickable links

#### Embedded Interactive Charts
- **Static images replaced with live charts**:
  - Convergence plot (Recharts)
  - Design space scatter (Recharts or Plotly)
  - Parameter importance (Recharts)
  - Optuna visualizations (converted to Plotly/Recharts)
- **Hover tooltips**: Show trial details on hover
- **Zoom/pan**: Interactive exploration
- **Toggle series**: Show/hide data series

#### Navigation Sidebar
- **Auto-generated TOC**: From markdown headings
- **Smooth scrolling**: Click heading → scroll to section
- **Active section highlighting**: Current visible section

#### Live Report Mode
- **Watch for changes**: File watcher on `OPTIMIZATION_REPORT.md`
- **Auto-refresh**: When report is regenerated
- **Notification**: "Report updated - click to reload"

#### Data Downloads
- **Markdown report**: Raw `.md` file
- **Trial data**: JSON export of `optimization_history_incremental.json`
- **Charts**: High-res PNG/SVG exports
- **Full study**: Zip archive of entire study folder

### API Endpoints

```python
# backend/api/routes/reports.py

@router.get("/studies/{study_id}/report")
async def get_report(study_id: str):
    """Get markdown report content (reads 3_reports/OPTIMIZATION_REPORT.md)"""

@router.get("/studies/{study_id}/report/charts/{chart_name}")
async def get_chart(study_id: str, chart_name: str):
    """Get chart image (PNG/SVG)"""

@router.get("/studies/{study_id}/download")
async def download_study(study_id: str, format: str = "json"):
    """Download study data (JSON, CSV, or ZIP)"""

@router.post("/studies/{study_id}/report/regenerate")
async def regenerate_report(study_id: str):
    """Regenerate report from current data"""
```

---

## Implementation Phases

### Phase 1: Backend Foundation (Week 1)
**Goal**: Create FastAPI backend with basic study management

**Tasks**:
1. Set up FastAPI project structure
2. Implement study CRUD endpoints
3. Create optimization control endpoints (start/stop/status)
4. Add file upload handling
5. Integrate with existing Atomizer modules
6. Write API documentation (Swagger)

**Files to Create**:
- `backend/api/main.py`
- `backend/api/routes/studies.py`
- `backend/api/routes/optimization.py`
- `backend/api/services/study_service.py`
- `backend/requirements.txt`

**Deliverable**: Working REST API for study management

---

### Phase 2: Frontend Shell (Week 2)
**Goal**: Create React app with routing and basic UI

**Tasks**:
1. Set up Vite + React + TypeScript project
2. Configure TailwindCSS
3. Create page routing (Configurator, Dashboard, Results)
4. Build basic layout components (Header, Sidebar, Footer)
5. Implement study list view
6. Connect to backend API (React Query setup)

**Files to Create**:
- `frontend/src/App.tsx`
- `frontend/src/pages/*.tsx`
- `frontend/src/components/Layout.tsx`
- `frontend/src/hooks/useStudies.ts`
- `frontend/package.json`

**Deliverable**: Navigable UI shell with API integration

---

### Phase 3: Study Configurator Page (Week 3)
**Goal**: Functional study creation interface

**Tasks**:
1. Build study configuration form
2. Add file upload (drag-and-drop)
3. Design variable management (add/remove)
4. Optimization settings panel
5. Form validation
6. Study creation workflow
7. Recent studies list

**Files to Create**:
- `frontend/src/pages/Configurator.tsx`
- `frontend/src/components/StudyForm.tsx`
- `frontend/src/components/FileUpload.tsx`
- `frontend/src/components/VariableEditor.tsx`

**Deliverable**: Working study creation form

---

### Phase 4: Real-Time Dashboard (Week 4-5)
**Goal**: Live optimization monitoring

**Tasks**:
1. Implement WebSocket connection
2. Build real-time charts (Recharts):
   - Convergence plot
   - Parameter space scatter
   - Parameter importance
3. Create trial table with auto-update
4. Add control panel (start/stop/pause)
5. System stats display
6. Pruning diagnostics integration
7. File watcher for `optimization_history_incremental.json`

**Files to Create**:
- `frontend/src/pages/Dashboard.tsx`
- `frontend/src/components/LiveCharts.tsx`
- `frontend/src/components/TrialTable.tsx`
- `frontend/src/hooks/useWebSocket.ts`
- `backend/api/websocket/optimization_stream.py`

**Deliverable**: Real-time optimization dashboard

---

### Phase 5: Results Viewer (Week 6)
**Goal**: Rich markdown report display

**Tasks**:
1. Markdown rendering (react-markdown)
2. Code syntax highlighting
3. Embedded interactive charts
4. Navigation sidebar (auto-generated TOC)
5. Live report mode (file watcher)
6. Data download endpoints
7. Chart export functionality

**Files to Create**:
- `frontend/src/pages/Results.tsx`
- `frontend/src/components/MarkdownReport.tsx`
- `frontend/src/components/ReportNavigation.tsx`
- `backend/api/routes/reports.py`

**Deliverable**: Complete results viewer

---

### Phase 6: LLM Integration (Future - Week 7-8)
**Goal**: Chat-based study configuration

**Tasks**:
1. Backend LLM integration:
   - Claude API client
   - Context management (uploaded files, PROTOCOL.md)
   - Configuration generation from natural language
2. Frontend chat interface:
   - Chat UI component
   - Message streaming
   - Configuration preview
   - Apply/reject buttons
3. Iterative refinement workflow

**Files to Create**:
- `backend/api/routes/llm.py`
- `backend/api/services/llm_service.py`
- `frontend/src/components/LLMChat.tsx`

**Deliverable**: LLM-assisted study configuration

---

### Phase 7: Polish & Deployment (Week 9)
**Goal**: Production-ready deployment

**Tasks**:
1. Error handling and loading states
2. Responsive design (mobile-friendly)
3. Performance optimization
4. Security (CORS, authentication future)
5. Docker containerization
6. Deployment documentation
7. User guide

**Deliverables**:
- Docker compose setup
- Deployment guide
- User documentation

---

## Technical Specifications

### WebSocket Protocol

#### Client → Server
```json
{
  "action": "subscribe",
  "study_id": "circular_plate_frequency_tuning"
}
```

#### Server → Client Events
```json
// Trial completed
{
  "type": "trial_completed",
  "data": {
    "trial_number": 23,
    "objective": 0.234,
    "params": { "diameter": 94.5, "thickness": 6.2 },
    "status": "success",
    "timestamp": "2025-11-21T10:30:45"
  }
}

// New best trial
{
  "type": "new_best",
  "data": {
    "trial_number": 20,
    "objective": 0.185,
    "params": { "diameter": 94.07, "thickness": 6.14 }
  }
}

// Progress update
{
  "type": "progress",
  "data": {
    "current": 23,
    "total": 50,
    "elapsed_seconds": 932,
    "eta_seconds": 1080,
    "status": "running"
  }
}

// Status change
{
  "type": "status_change",
  "data": {
    "status": "completed",
    "reason": "Target achieved"
  }
}
```

### File Watching Strategy

Use **watchdog** (Python) to monitor JSON files:
- `optimization_history_incremental.json` - Trial updates
- `pruning_history.json` - Pruning events
- `OPTIMIZATION_REPORT.md` - Report regeneration

```python
# backend/api/services/file_watcher.py

from watchdog.observers import Observer
from watchdog.events import FileSystemEventHandler

class OptimizationWatcher(FileSystemEventHandler):
    def on_modified(self, event):
        if event.src_path.endswith('optimization_history_incremental.json'):
            # Read updated file
            # Broadcast to WebSocket clients
            await broadcast_update(study_id, new_trial_data)
```

---

## Security Considerations

### Authentication (Future Phase)
- **JWT tokens**: Secure API access
- **Session management**: User login/logout
- **Role-based access**: Admin vs. read-only users

### File Upload Security
- **File type validation**: Only .prt, .sim, .fem allowed
- **Size limits**: Max 100 MB per file
- **Virus scanning** (future): ClamAV integration
- **Sandboxed storage**: Isolated study folders

### API Rate Limiting
- **Per-endpoint limits**: Prevent abuse
- **WebSocket connection limits**: Max 10 concurrent per study

---

## Performance Optimization

### Backend
- **Async I/O**: All file operations async
- **Caching**: Redis for study metadata (future)
- **Pagination**: Large trial lists paginated
- **Compression**: Gzip responses

### Frontend
- **Code splitting**: Route-based chunks
- **Lazy loading**: Charts load on demand
- **Virtual scrolling**: Large trial tables
- **Image optimization**: Lazy load chart images
- **Service worker** (future): Offline support

---

## Deployment Options

### Option 1: Local Development Server
```bash
# Start backend
cd backend
python -m uvicorn api.main:app --reload

# Start frontend
cd frontend
npm run dev
```

### Option 2: Docker Compose (Production)
```yaml
# docker-compose.yml

version: '3.8'

services:
  backend:
    build: ./backend
    ports:
      - "8000:8000"
    volumes:
      - ./studies:/app/studies
    environment:
      - NX_PATH=/usr/local/nx2412

  frontend:
    build: ./frontend
    ports:
      - "3000:3000"
    depends_on:
      - backend

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf
    depends_on:
      - frontend
      - backend
```

### Option 3: Cloud Deployment (Future)
- **Backend**: AWS Lambda / Google Cloud Run
- **Frontend**: Vercel / Netlify
- **Database**: AWS RDS / Google Cloud SQL
- **File storage**: AWS S3 / Google Cloud Storage

---

## Future Enhancements

### Advanced Features
1. **Multi-user collaboration**: Shared studies, comments
2. **Study comparison**: Side-by-side comparison of studies
3. **Experiment tracking**: MLflow integration
4. **Version control**: Git-like versioning for studies
5. **Automated reporting**: Scheduled report generation
6. **Email notifications**: Optimization complete alerts
7. **Mobile app**: React Native companion app

### Integrations
1. **CAD viewers**: Embed 3D model viewer (Three.js)
2. **Simulation previews**: Show mesh/results in browser
3. **Cloud solvers**: Run Nastran in cloud
4. **Jupyter notebooks**: Embedded analysis notebooks
5. **CI/CD**: Automated testing for optimization workflows

---

## Success Metrics

### User Experience
- **Study creation time**: < 5 minutes (manual), < 2 minutes (LLM)
- **Dashboard refresh rate**: < 1 second latency
- **Report load time**: < 2 seconds

### System Performance
- **WebSocket latency**: < 100ms
- **API response time**: < 200ms (p95)
- **Concurrent users**: Support 10+ simultaneous optimizations

---

## Dependencies

### Backend
```
fastapi>=0.104.0
uvicorn[standard]>=0.24.0
python-multipart>=0.0.6
watchdog>=3.0.0
optuna>=3.4.0
pynastran>=1.4.0
python-socketio>=5.10.0
aiofiles>=23.2.1
```

### Frontend
```
react>=18.2.0
react-router-dom>=6.18.0
@tanstack/react-query>=5.8.0
recharts>=2.10.0
react-markdown>=9.0.0
socket.io-client>=4.7.0
tailwindcss>=3.3.5
```

---

## Next Steps

1. **Review this plan**: Discuss architecture, tech stack, priorities
2. **Prototype Phase 1**: Build minimal FastAPI backend
3. **Design mockups**: High-fidelity UI designs (Figma)
4. **Set up development environment**: Create project structure
5. **Begin Phase 1 implementation**: Backend foundation

---

**Confirmed Decisions** ✅:
1. **Architecture**: REST + WebSocket
2. **Deployment**: Self-hosted (local/Docker)
3. **Authentication**: Future phase
4. **Design**: Desktop-first
5. **Implementation Priority**: Live Dashboard → Study Configurator → Results Viewer

---

**Status**: ✅ Approved - Implementation starting with Phase 4 (Live Dashboard)
