# Dashboard Chat Architecture - Task List

**For**: Ralph Loop Execution
**Plan Document**: [DASHBOARD_CHAT_ARCHITECTURE.md](./DASHBOARD_CHAT_ARCHITECTURE.md)
**Created**: 2025-01-08

---

## Execution Order

Execute phases in order. Within each phase, tasks can be parallelized where noted.

---

## PHASE 1: MCP Server Foundation

**Goal**: Create Atomizer MCP server that exposes tools to Claude

### P1.1 - Create MCP Server Scaffold [BLOCKING]

**Description**: Set up the MCP server project structure

**Files to create**:
- `mcp-server/atomizer-tools/package.json`
- `mcp-server/atomizer-tools/tsconfig.json`
- `mcp-server/atomizer-tools/src/index.ts`
- `mcp-server/atomizer-tools/src/utils/paths.ts`

**Acceptance Criteria**:
- [ ] `npm install` succeeds
- [ ] `npm run build` succeeds
- [ ] Server starts without errors

**Reference**: See DASHBOARD_CHAT_ARCHITECTURE.md section "Phase 1: MCP Server Foundation"

---

### P1.2 - Implement Study Tools [CAN PARALLELIZE with P1.3-P1.6]

**Description**: Create tools for study management

**File**: `mcp-server/atomizer-tools/src/tools/study.ts`

**Tools to implement**:
1. `list_studies` - List all available studies with status
2. `get_study_status` - Get detailed status of a study
3. `create_study` - Create study from natural language description

**Dependencies**: P1.1

**Acceptance Criteria**:
- [ ] list_studies returns array of {name, status, trials}
- [ ] get_study_status returns config + results summary
- [ ] create_study calls Python StudyCreator

---

### P1.3 - Implement Optimization Tools [CAN PARALLELIZE]

**Description**: Create tools for running optimizations

**File**: `mcp-server/atomizer-tools/src/tools/optimization.ts`

**Tools to implement**:
1. `run_optimization` - Start optimization for a study
2. `stop_optimization` - Stop running optimization
3. `get_optimization_status` - Get current optimization state

**Dependencies**: P1.1

**Acceptance Criteria**:
- [ ] run_optimization spawns Python process
- [ ] stop_optimization terminates gracefully
- [ ] get_optimization_status reads from DB

---

### P1.4 - Implement Analysis Tools [CAN PARALLELIZE]

**Description**: Create tools for analyzing results

**File**: `mcp-server/atomizer-tools/src/tools/analysis.ts`

**Tools to implement**:
1. `get_trial_data` - Query trials with filters
2. `analyze_convergence` - Convergence analysis
3. `compare_trials` - Compare multiple trials
4. `get_best_design` - Get best design found

**Dependencies**: P1.1

**Acceptance Criteria**:
- [ ] get_trial_data supports: all, best, pareto, recent, failed
- [ ] analyze_convergence returns trend metrics
- [ ] compare_trials returns comparison table

---

### P1.5 - Implement Reporting Tools [CAN PARALLELIZE]

**Description**: Create tools for generating reports

**File**: `mcp-server/atomizer-tools/src/tools/reporting.ts`

**Tools to implement**:
1. `generate_report` - Generate markdown report
2. `export_data` - Export results to CSV/JSON

**Dependencies**: P1.1

**Acceptance Criteria**:
- [ ] generate_report creates valid markdown
- [ ] export_data creates valid CSV/JSON files

---

### P1.6 - Implement Physics Tools [CAN PARALLELIZE]

**Description**: Create tools for FEA explanations

**File**: `mcp-server/atomizer-tools/src/tools/physics.ts`

**Tools to implement**:
1. `explain_physics` - Explain FEA concepts
2. `recommend_method` - Recommend optimization method
3. `query_extractors` - List available extractors

**Dependencies**: P1.1

**Acceptance Criteria**:
- [ ] explain_physics uses Atomizer context
- [ ] recommend_method considers objectives/DVs

---

### P1.7 - Implement Admin Tools (Power Mode) [AFTER P1.2-P1.6]

**Description**: Create tools for power mode (code modification)

**File**: `mcp-server/atomizer-tools/src/tools/admin.ts`

**Tools to implement**:
1. `edit_file` - Edit file in codebase
2. `create_file` - Create new file
3. `create_extractor` - Create new physics extractor
4. `run_shell_command` - Run arbitrary shell command
5. `search_codebase` - Search files

**Dependencies**: P1.2-P1.6 (understand patterns first)

**Acceptance Criteria**:
- [ ] edit_file validates old_content exists
- [ ] create_extractor follows template
- [ ] run_shell_command captures output

**SECURITY**: These tools ONLY available when ATOMIZER_MODE=power

---

### P1.8 - Build and Register MCP Server [BLOCKING]

**Description**: Build server and update Claude config

**Steps**:
1. `cd mcp-server/atomizer-tools && npm run build`
2. Update `.claude/settings.local.json` with MCP config
3. Test with `claude --mcp-config`

**Dependencies**: P1.1-P1.7

**Acceptance Criteria**:
- [ ] Server builds without errors
- [ ] Claude can list tools
- [ ] Tools execute correctly

---

## PHASE 2: Backend Session Manager

**Goal**: Manage persistent Claude sessions with MCP

### P2.1 - Create Conversation Store [BLOCKING]

**Description**: SQLite persistence for conversations

**File**: `atomizer-dashboard/backend/api/services/conversation_store.py`

**Features**:
- Sessions table (id, mode, study_id, timestamps)
- Messages table (id, session_id, role, content, tool_calls, timestamp)
- CRUD operations

**Acceptance Criteria**:
- [ ] Database schema created on init
- [ ] add_message stores correctly
- [ ] get_history returns chronological messages

---

### P2.2 - Create Context Builder [CAN PARALLELIZE with P2.1]

**Description**: Build context prompts for Claude

**File**: `atomizer-dashboard/backend/api/services/context_builder.py`

**Features**:
- Base context (identity, capabilities)
- Study context (config, results)
- Mode instructions (user vs power)
- Conversation history injection

**Acceptance Criteria**:
- [ ] User mode context restricts capabilities
- [ ] Power mode context enables all tools
- [ ] Study context includes config + status

---

### P2.3 - Create Session Manager [AFTER P2.1, P2.2]

**Description**: Manage Claude Code subprocess sessions

**File**: `atomizer-dashboard/backend/api/services/session_manager.py`

**Features**:
- Create session (spawn Claude subprocess)
- Send message (stdin/stdout communication)
- Stream response (async generator)
- Switch mode (restart with new config)
- Cleanup stale sessions

**Acceptance Criteria**:
- [ ] Sessions persist across messages
- [ ] Mode switching works
- [ ] Cleanup runs periodically

---

### P2.4 - Update API Routes [AFTER P2.3]

**Description**: Add new Claude API endpoints

**File**: `atomizer-dashboard/backend/api/routes/claude.py`

**Endpoints**:
- `POST /sessions` - Create/resume session
- `POST /sessions/{id}/mode` - Switch mode
- `WS /sessions/{id}/ws` - WebSocket for chat
- Keep legacy endpoints for backwards compatibility

**Acceptance Criteria**:
- [ ] Session creation returns session_id
- [ ] WebSocket streams responses
- [ ] Mode switch requires confirmation

---

### P2.5 - Update Main Entry Point [AFTER P2.4]

**Description**: Initialize session manager on startup

**File**: `atomizer-dashboard/backend/main.py`

**Changes**:
- Add lifespan handler
- Start session manager on startup
- Stop session manager on shutdown

**Acceptance Criteria**:
- [ ] Manager starts with server
- [ ] Manager stops cleanly

---

## PHASE 3: Frontend Updates

**Goal**: Update React UI for new chat system

### P3.1 - Create Mode Toggle Component [CAN PARALLELIZE]

**Description**: User/Power mode switcher

**File**: `atomizer-dashboard/frontend/src/components/chat/ModeToggle.tsx`

**Features**:
- Toggle buttons for User/Power mode
- Confirmation modal for Power mode
- Visual indication of current mode

**Acceptance Criteria**:
- [ ] User mode is default
- [ ] Power mode requires confirmation
- [ ] Visual feedback on mode change

---

### P3.2 - Create Tool Call Card Component [CAN PARALLELIZE]

**Description**: Display tool calls in messages

**File**: `atomizer-dashboard/frontend/src/components/chat/ToolCallCard.tsx`

**Features**:
- Expandable card showing tool name
- Arguments display
- Result display (success/error)
- Loading state

**Acceptance Criteria**:
- [ ] Shows tool name and status
- [ ] Expandable to show details
- [ ] Error states displayed clearly

---

### P3.3 - Update useChat Hook [AFTER P3.1, P3.2]

**Description**: WebSocket-based chat with sessions

**File**: `atomizer-dashboard/frontend/src/hooks/useChat.ts`

**Changes**:
- Session creation on mount
- WebSocket connection management
- Tool call handling in messages
- Mode switching
- Reconnection logic

**Acceptance Criteria**:
- [ ] Session created on mount
- [ ] WebSocket connects and streams
- [ ] Tool calls rendered in messages
- [ ] Mode switch triggers reconnect

---

### P3.4 - Update ChatMessage Component [CAN PARALLELIZE with P3.3]

**Description**: Support tool calls in messages

**File**: `atomizer-dashboard/frontend/src/components/chat/ChatMessage.tsx`

**Changes**:
- Import and render ToolCallCard
- Update Message interface for toolCalls

**Acceptance Criteria**:
- [ ] Tool calls render inline
- [ ] Markdown still works
- [ ] Streaming cursor shows

---

### P3.5 - Update ChatPane Component [AFTER P3.3, P3.4]

**Description**: Integrate new components

**File**: `atomizer-dashboard/frontend/src/components/chat/ChatPane.tsx`

**Changes**:
- Add ModeToggle to header
- Show connection status
- Power mode indicator bar
- Pass mode to useChat

**Acceptance Criteria**:
- [ ] Mode toggle visible
- [ ] Connection status shows
- [ ] Power mode has warning bar

---

### P3.6 - Update Component Exports [AFTER P3.1-P3.5]

**Description**: Export new components

**File**: `atomizer-dashboard/frontend/src/components/chat/index.ts`

**Changes**:
- Export ModeToggle
- Export ToolCallCard

---

## PHASE 4: Integration & Testing

**Goal**: Ensure everything works together

### P4.1 - Integration Test: User Mode [AFTER P1-P3]

**Test cases**:
- [ ] Create new session
- [ ] Send message, receive response
- [ ] Tool call: list_studies
- [ ] Tool call: get_study_status
- [ ] Tool call: create_study
- [ ] Session persists across page refresh

---

### P4.2 - Integration Test: Power Mode [AFTER P4.1]

**Test cases**:
- [ ] Switch to power mode
- [ ] Tool call: edit_file
- [ ] Tool call: create_extractor
- [ ] Tool call: run_shell_command
- [ ] Verify changes in filesystem

---

### P4.3 - Integration Test: Study Context [AFTER P4.1]

**Test cases**:
- [ ] Navigate to study
- [ ] Chat knows study context
- [ ] Tool calls use study context
- [ ] Context updates on study change

---

### P4.4 - Performance Testing [AFTER P4.1-P4.3]

**Test cases**:
- [ ] Response streaming is smooth
- [ ] No memory leaks in sessions
- [ ] Cleanup works for stale sessions
- [ ] Multiple concurrent sessions

---

### P4.5 - Documentation Update [AFTER P4.1-P4.4]

**Files to update**:
- [ ] README.md - Add chat architecture section
- [ ] CLAUDE.md - Reference new MCP tools
- [ ] Add user guide for chat modes

---

## Quick Reference: File Map

```
CREATE:
├── mcp-server/atomizer-tools/
│   ├── package.json
│   ├── tsconfig.json
│   └── src/
│       ├── index.ts
│       ├── tools/
│       │   ├── study.ts
│       │   ├── optimization.ts
│       │   ├── analysis.ts
│       │   ├── reporting.ts
│       │   ├── physics.ts
│       │   └── admin.ts
│       └── utils/
│           └── paths.ts
│
├── atomizer-dashboard/backend/api/services/
│   ├── conversation_store.py
│   ├── context_builder.py
│   └── session_manager.py
│
└── atomizer-dashboard/frontend/src/components/chat/
    ├── ModeToggle.tsx
    └── ToolCallCard.tsx

UPDATE:
├── atomizer-dashboard/backend/api/routes/claude.py
├── atomizer-dashboard/backend/main.py
├── atomizer-dashboard/frontend/src/hooks/useChat.ts
├── atomizer-dashboard/frontend/src/components/chat/ChatMessage.tsx
├── atomizer-dashboard/frontend/src/components/chat/ChatPane.tsx
└── atomizer-dashboard/frontend/src/components/chat/index.ts
```

---

## Estimated Effort

| Phase | Tasks | Estimated Hours |
|-------|-------|-----------------|
| Phase 1 | 8 | 6-8 |
| Phase 2 | 5 | 4-6 |
| Phase 3 | 6 | 4-5 |
| Phase 4 | 5 | 3-4 |
| **Total** | **24** | **17-23** |

---

## Notes for Ralph Loop

1. **Read the full plan first**: `docs/plans/DASHBOARD_CHAT_ARCHITECTURE.md`
2. **Execute in order**: Phase 1 → Phase 2 → Phase 3 → Phase 4
3. **Parallelize where noted**: Tasks marked "CAN PARALLELIZE" can run concurrently
4. **Test incrementally**: Each phase should be tested before moving on
5. **Commit after each phase**: Keep changes atomic and reversible

---

*Task List Version: 1.0*