530 lines
27 KiB
Markdown
530 lines
27 KiB
Markdown
|
# Atomizer Component Relationships
|
||
|
|
|
||
|
|
**Date**: January 2026
|
||
|
|
**Version**: 2.0
|
||
|
|
|
||
|
|
This document details how Atomizer's components interact with each other.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 1. Configuration Files Hierarchy
|
||
|
|
|
||
|
|
```
|
||
|
|
┌─────────────────────────────────────────────────────────────────┐
|
||
|
|
│ atomizer_spec.json (v2.0) │
|
||
|
|
│ SINGLE SOURCE OF TRUTH │
|
||
|
|
└───────────────────────────┬─────────────────────────────────────┘
|
||
|
|
│
|
||
|
|
┌───────────────────┼───────────────────┐
|
||
|
|
│ │ │
|
||
|
|
▼ ▼ ▼
|
||
|
|
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
|
||
|
|
│ Canvas UI │ │ Backend API │ │ Opt Engine │
|
||
|
|
│ (ReactFlow) │ │ (FastAPI) │ │ (Python) │
|
||
|
|
└───────────────┘ └───────────────┘ └───────────────┘
|
||
|
|
```
|
||
|
|
|
||
|
|
### Relationship Table
|
||
|
|
|
||
|
|
| Component | Reads From | Writes To | Frequency |
|
||
|
|
|-----------|------------|-----------|-----------|
|
||
|
|
| Canvas (React) | atomizer_spec.json | atomizer_spec.json | Real-time |
|
||
|
|
| Backend (FastAPI) | atomizer_spec.json | atomizer_spec.json | Per request |
|
||
|
|
| Engine (Python) | atomizer_spec.json | study.db | Per trial |
|
||
|
|
| Claude Agent | atomizer_spec.json | atomizer_spec.json | Per command |
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 2. Frontend Store Dependencies
|
||
|
|
|
||
|
|
```
|
||
|
|
┌─────────────────────┐
|
||
|
|
│ useSpecStore │
|
||
|
|
│ (Zustand) │
|
||
|
|
│ │
|
||
|
|
│ spec: AtomizerSpec │
|
||
|
|
│ hash: string │
|
||
|
|
│ isDirty: boolean │
|
||
|
|
│ selectedNodeId │
|
||
|
|
└──────────┬──────────┘
|
||
|
|
│
|
||
|
|
┌───────────────────┼───────────────────┐
|
||
|
|
│ │ │
|
||
|
|
▼ ▼ ▼
|
||
|
|
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
|
||
|
|
│ CanvasView │ │ NodeConfig │ │ Validation │
|
||
|
|
│ │ │ Panel │ │ Panel │
|
||
|
|
│ Subscribes: │ │ │ │ │
|
||
|
|
│ - spec │ │ Subscribes: │ │ Subscribes: │
|
||
|
|
│ - hash │ │ - spec │ │ - validation │
|
||
|
|
│ - isDirty │ │ - selected │ │ │
|
||
|
|
└──────────────┘ └──────────────┘ └──────────────┘
|
||
|
|
|
||
|
|
┌─────────────────────┐
|
||
|
|
│ useChat │
|
||
|
|
│ (Hook) │
|
||
|
|
│ │
|
||
|
|
│ messages: Message[] │
|
||
|
|
│ isThinking: bool │
|
||
|
|
│ mode: user|power │
|
||
|
|
│ sessionId: string │
|
||
|
|
└──────────┬──────────┘
|
||
|
|
│
|
||
|
|
▼
|
||
|
|
┌─────────────────────┐
|
||
|
|
│ ChatPanel │
|
||
|
|
│ │
|
||
|
|
│ Displays messages │
|
||
|
|
│ Tool call cards │
|
||
|
|
│ Mode toggle │
|
||
|
|
└─────────────────────┘
|
||
|
|
```
|
||
|
|
|
||
|
|
### State Flow
|
||
|
|
|
||
|
|
1. **User edits node** → `useSpecStore.patchSpec(path, value)`
|
||
|
|
2. **Optimistic update** → UI immediately reflects change
|
||
|
|
3. **Async PATCH** → Backend validates and saves
|
||
|
|
4. **WebSocket broadcast** → All clients receive `spec_updated`
|
||
|
|
5. **Hash comparison** → Check for conflicts
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 3. Backend Service Dependencies
|
||
|
|
|
||
|
|
```
|
||
|
|
┌─────────────────────────────────────────────────────────────────┐
|
||
|
|
│ FastAPI App │
|
||
|
|
└─────────────────────────────────────────────────────────────────┘
|
||
|
|
│
|
||
|
|
┌──────────────────────┼──────────────────────┐
|
||
|
|
│ │ │
|
||
|
|
▼ ▼ ▼
|
||
|
|
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
|
||
|
|
│ spec.py │ │ claude.py │ │optimization.py│
|
||
|
|
│ (Routes) │ │ (Routes) │ │ (Routes) │
|
||
|
|
└───────┬───────┘ └───────┬───────┘ └───────┬───────┘
|
||
|
|
│ │ │
|
||
|
|
▼ ▼ ▼
|
||
|
|
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
|
||
|
|
│ SpecManager │◄─────│ClaudeAgent │ │ Runner │
|
||
|
|
│ │ │ │ │ (subprocess) │
|
||
|
|
│ - load_spec() │ │ - tools │ │ │
|
||
|
|
│ - save_spec() │ │ - chat() │ │ - run() │
|
||
|
|
│ - patch_spec()│ │ │ │ - stream() │
|
||
|
|
│ - broadcast() │ │ │ │ │
|
||
|
|
└───────┬───────┘ └───────┬───────┘ └───────┬───────┘
|
||
|
|
│ │ │
|
||
|
|
└──────────────────────┼──────────────────────┘
|
||
|
|
│
|
||
|
|
▼
|
||
|
|
┌─────────────────────┐
|
||
|
|
│ atomizer_spec.json │
|
||
|
|
│ (Disk) │
|
||
|
|
└─────────────────────┘
|
||
|
|
```
|
||
|
|
|
||
|
|
### Service Responsibilities
|
||
|
|
|
||
|
|
| Service | Responsibility | Dependencies |
|
||
|
|
|---------|---------------|--------------|
|
||
|
|
| SpecManager | All spec CRUD, validation, broadcasting | Pydantic models |
|
||
|
|
| ClaudeAgent | AI chat with tools, context building | Anthropic API, SpecManager |
|
||
|
|
| ContextBuilder | System prompt assembly | Study data, canvas state |
|
||
|
|
| SessionManager | WebSocket lifecycle | In-memory store |
|
||
|
|
| Runner | Optimization loop | NX solver, extractors |
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 4. Optimization Engine Module Dependencies
|
||
|
|
|
||
|
|
```
|
||
|
|
┌─────────────────────────────────────────────────────────────────┐
|
||
|
|
│ optimization_engine/ │
|
||
|
|
└─────────────────────────────────────────────────────────────────┘
|
||
|
|
|
||
|
|
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
|
||
|
|
│ config/ │ │ core/ │ │ nx/ │
|
||
|
|
│ │ │ │ │ │
|
||
|
|
│spec_models │◄─────│ runner │─────►│ solver │
|
||
|
|
│spec_validator│ │ IMSO │ │ updater │
|
||
|
|
│ migrator │ │ gradient │ │ session │
|
||
|
|
└──────┬──────┘ └──────┬──────┘ └─────────────┘
|
||
|
|
│ │
|
||
|
|
│ ┌──────┴──────┐
|
||
|
|
│ │ │
|
||
|
|
│ ▼ ▼
|
||
|
|
│ ┌─────────────┐ ┌─────────────┐
|
||
|
|
│ │ extractors/ │ │ surrogates │
|
||
|
|
│ │ │ │ │
|
||
|
|
│ │displacement │ │ MLP │
|
||
|
|
│ │ stress │ │ GNN │
|
||
|
|
│ │ zernike │ │ ensemble │
|
||
|
|
│ │ custom │ │ │
|
||
|
|
│ └─────────────┘ └─────────────┘
|
||
|
|
│
|
||
|
|
▼
|
||
|
|
┌─────────────┐ ┌─────────────┐
|
||
|
|
│ study/ │ │ utils/ │
|
||
|
|
│ │ │ │
|
||
|
|
│ creator │ │dashboard_db │
|
||
|
|
│ state │ │trial_manager│
|
||
|
|
│ reset │ │ archiver │
|
||
|
|
└─────────────┘ └─────────────┘
|
||
|
|
```
|
||
|
|
|
||
|
|
### Module Interaction Flow
|
||
|
|
|
||
|
|
```
|
||
|
|
atomizer_spec.json
|
||
|
|
│
|
||
|
|
▼
|
||
|
|
┌───────────────┐
|
||
|
|
│ spec_models │ ← Pydantic validation
|
||
|
|
└───────┬───────┘
|
||
|
|
│
|
||
|
|
▼
|
||
|
|
┌───────────────┐
|
||
|
|
│ runner │ ← Main optimization loop
|
||
|
|
└───────┬───────┘
|
||
|
|
│
|
||
|
|
┌───────┴───────┐
|
||
|
|
│ │
|
||
|
|
▼ ▼
|
||
|
|
┌─────────┐ ┌─────────┐
|
||
|
|
│ nx/ │ │extract/ │
|
||
|
|
│ solver │ │ors │
|
||
|
|
└────┬────┘ └────┬────┘
|
||
|
|
│ │
|
||
|
|
└─────┬─────┘
|
||
|
|
│
|
||
|
|
▼
|
||
|
|
┌─────────────┐
|
||
|
|
│ study.db │ ← Trial persistence
|
||
|
|
└─────────────┘
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 5. WebSocket Event Flow
|
||
|
|
|
||
|
|
### 5.1 Spec Sync WebSocket
|
||
|
|
|
||
|
|
```
|
||
|
|
Frontend Backend File System
|
||
|
|
│ │ │
|
||
|
|
│ ── PATCH /spec ──────► │ │
|
||
|
|
│ │ ── write ──────────────► │
|
||
|
|
│ │ ◄── confirm ──────────── │
|
||
|
|
│ │ │
|
||
|
|
│ ◄── spec_updated ───── │ ← broadcast to all │
|
||
|
|
│ │ │
|
||
|
|
│ (update local hash) │ │
|
||
|
|
```
|
||
|
|
|
||
|
|
### 5.2 Claude Chat WebSocket
|
||
|
|
|
||
|
|
```
|
||
|
|
Frontend Backend Claude API
|
||
|
|
│ │ │
|
||
|
|
│ ── message + state ──► │ │
|
||
|
|
│ │ ── prompt ─────────────► │
|
||
|
|
│ │ ◄── tool_call ────────── │
|
||
|
|
│ ◄── tool_call ──────── │ │
|
||
|
|
│ │ (execute tool) │
|
||
|
|
│ │ ── tool_result ────────► │
|
||
|
|
│ ◄── tool_result ────── │ ◄── response ─────────── │
|
||
|
|
│ ◄── text ───────────── │ │
|
||
|
|
│ ◄── done ───────────── │ │
|
||
|
|
│ │ │
|
||
|
|
│ (if spec_modified) │ │
|
||
|
|
│ ◄── spec_modified ──── │ │
|
||
|
|
│ (reload spec) │ │
|
||
|
|
```
|
||
|
|
|
||
|
|
### 5.3 Optimization Stream WebSocket
|
||
|
|
|
||
|
|
```
|
||
|
|
Frontend Backend Runner Process
|
||
|
|
│ │ │
|
||
|
|
│ ── start_opt ────────► │ ── spawn ──────────────► │
|
||
|
|
│ │ │
|
||
|
|
│ │ ◄── trial_start ──────── │
|
||
|
|
│ ◄── trial_start ────── │ │
|
||
|
|
│ │ │
|
||
|
|
│ │ ◄── trial_complete ───── │
|
||
|
|
│ ◄── trial_complete ─── │ │
|
||
|
|
│ │ │
|
||
|
|
│ (repeat for N trials) │ │
|
||
|
|
│ │ │
|
||
|
|
│ ◄── optimization_done ─ │ ◄── done ─────────────── │
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 6. Data Transformation Pipeline
|
||
|
|
|
||
|
|
### 6.1 Canvas → Spec → ReactFlow
|
||
|
|
|
||
|
|
```
|
||
|
|
User interacts with Canvas
|
||
|
|
│
|
||
|
|
▼
|
||
|
|
┌─────────────────────────┐
|
||
|
|
│ ReactFlow onChange │
|
||
|
|
│ (nodes, edges) │
|
||
|
|
└───────────┬─────────────┘
|
||
|
|
│
|
||
|
|
▼
|
||
|
|
┌─────────────────────────┐
|
||
|
|
│ useSpecStore.patch() │
|
||
|
|
│ JSONPath modification │
|
||
|
|
└───────────┬─────────────┘
|
||
|
|
│
|
||
|
|
▼
|
||
|
|
┌─────────────────────────┐
|
||
|
|
│ Backend SpecManager │
|
||
|
|
│ Pydantic validation │
|
||
|
|
└───────────┬─────────────┘
|
||
|
|
│
|
||
|
|
▼
|
||
|
|
┌─────────────────────────┐
|
||
|
|
│ atomizer_spec.json │
|
||
|
|
│ (persisted) │
|
||
|
|
└───────────┬─────────────┘
|
||
|
|
│
|
||
|
|
▼
|
||
|
|
┌─────────────────────────┐
|
||
|
|
│ spec/converter.ts │
|
||
|
|
│ specToNodes() │
|
||
|
|
└───────────┬─────────────┘
|
||
|
|
│
|
||
|
|
▼
|
||
|
|
┌─────────────────────────┐
|
||
|
|
│ ReactFlow renders │
|
||
|
|
│ updated canvas │
|
||
|
|
└─────────────────────────┘
|
||
|
|
```
|
||
|
|
|
||
|
|
### 6.2 Spec → Optimization → Results
|
||
|
|
|
||
|
|
```
|
||
|
|
atomizer_spec.json
|
||
|
|
│
|
||
|
|
▼
|
||
|
|
┌─────────────────────────┐
|
||
|
|
│ Runner.load_config() │
|
||
|
|
│ Parse spec structure │
|
||
|
|
└───────────┬─────────────┘
|
||
|
|
│
|
||
|
|
▼
|
||
|
|
┌─────────────────────────┐
|
||
|
|
│ Optuna.create_study() │
|
||
|
|
│ Initialize sampler │
|
||
|
|
└───────────┬─────────────┘
|
||
|
|
│
|
||
|
|
┌────────┴────────┐
|
||
|
|
│ Trial Loop │
|
||
|
|
│ (1 to N) │
|
||
|
|
└────────┬────────┘
|
||
|
|
│
|
||
|
|
▼
|
||
|
|
┌─────────────────────────┐
|
||
|
|
│ NX solver.solve() │
|
||
|
|
│ Update expressions │
|
||
|
|
│ Run Nastran │
|
||
|
|
└───────────┬─────────────┘
|
||
|
|
│
|
||
|
|
▼
|
||
|
|
┌─────────────────────────┐
|
||
|
|
│ extractors.extract() │
|
||
|
|
│ Read OP2 results │
|
||
|
|
└───────────┬─────────────┘
|
||
|
|
│
|
||
|
|
▼
|
||
|
|
┌─────────────────────────┐
|
||
|
|
│ TrialManager.save() │
|
||
|
|
│ - params.json │
|
||
|
|
│ - results.json │
|
||
|
|
│ - study.db INSERT │
|
||
|
|
└─────────────────────────┘
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 7. Error Handling Chain
|
||
|
|
|
||
|
|
```
|
||
|
|
Frontend Error
|
||
|
|
│
|
||
|
|
├──► Validation Error (UI shows inline)
|
||
|
|
│
|
||
|
|
├──► Network Error (retry with exponential backoff)
|
||
|
|
│
|
||
|
|
└──► Conflict Error (409) → reload spec → show diff
|
||
|
|
|
||
|
|
Backend Error
|
||
|
|
│
|
||
|
|
├──► Pydantic ValidationError → 422 with field details
|
||
|
|
│
|
||
|
|
├──► SpecNotFoundError → 404
|
||
|
|
│
|
||
|
|
├──► SpecConflictError → 409 with current hash
|
||
|
|
│
|
||
|
|
└──► Internal Error → 500 with traceback (dev mode)
|
||
|
|
|
||
|
|
Engine Error
|
||
|
|
│
|
||
|
|
├──► NX Connection Error → retry with backoff
|
||
|
|
│
|
||
|
|
├──► Solver Error → mark trial FAILED, continue
|
||
|
|
│
|
||
|
|
├──► Extractor Error → log warning, use fallback
|
||
|
|
│
|
||
|
|
└──► Database Error → rollback transaction
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 8. Security Boundaries
|
||
|
|
|
||
|
|
```
|
||
|
|
┌─────────────────────────────────────────────────────────────────┐
|
||
|
|
│ User Browser │
|
||
|
|
│ │
|
||
|
|
│ ┌──────────────────────────────────────────────────────────┐ │
|
||
|
|
│ │ React Application │ │
|
||
|
|
│ │ - No direct file access │ │
|
||
|
|
│ │ - All data via REST/WebSocket │ │
|
||
|
|
│ └──────────────────────────────────────────────────────────┘ │
|
||
|
|
└─────────────────────────────────────────────────────────────────┘
|
||
|
|
│
|
||
|
|
(HTTP/WS)
|
||
|
|
│
|
||
|
|
▼
|
||
|
|
┌─────────────────────────────────────────────────────────────────┐
|
||
|
|
│ FastAPI Backend │
|
||
|
|
│ │
|
||
|
|
│ ┌──────────────────────────────────────────────────────────┐ │
|
||
|
|
│ │ Input Validation │ │
|
||
|
|
│ │ - Pydantic schema validation │ │
|
||
|
|
│ │ - Path sanitization │ │
|
||
|
|
│ │ - Rate limiting (optional) │ │
|
||
|
|
│ └──────────────────────────────────────────────────────────┘ │
|
||
|
|
│ │ │
|
||
|
|
│ ▼ │
|
||
|
|
│ ┌──────────────────────────────────────────────────────────┐ │
|
||
|
|
│ │ File System Access │ │
|
||
|
|
│ │ - Restricted to studies/ directory │ │
|
||
|
|
│ │ - No path traversal (../) │ │
|
||
|
|
│ └──────────────────────────────────────────────────────────┘ │
|
||
|
|
└─────────────────────────────────────────────────────────────────┘
|
||
|
|
│
|
||
|
|
▼
|
||
|
|
┌─────────────────────────────────────────────────────────────────┐
|
||
|
|
│ Optimization Engine │
|
||
|
|
│ │
|
||
|
|
│ - Runs as separate process │
|
||
|
|
│ - Limited to study directory │
|
||
|
|
│ - NX subprocess sandboxed │
|
||
|
|
└─────────────────────────────────────────────────────────────────┘
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 9. Deployment Topology
|
||
|
|
|
||
|
|
```
|
||
|
|
┌─────────────────────────────────────────────────────────────────┐
|
||
|
|
│ Development Environment │
|
||
|
|
│ │
|
||
|
|
│ Frontend: npm run dev → localhost:5173 │
|
||
|
|
│ Backend: uvicorn --reload → localhost:8001 │
|
||
|
|
│ NX: Local NX installation │
|
||
|
|
│ Claude: Anthropic API (cloud) │
|
||
|
|
└─────────────────────────────────────────────────────────────────┘
|
||
|
|
|
||
|
|
┌─────────────────────────────────────────────────────────────────┐
|
||
|
|
│ Production Environment │
|
||
|
|
│ │
|
||
|
|
│ Frontend: Static files served by Nginx │
|
||
|
|
│ Backend: Gunicorn + Uvicorn workers │
|
||
|
|
│ NX: Licensed NX server │
|
||
|
|
│ Database: SQLite (can upgrade to PostgreSQL) │
|
||
|
|
│ Claude: Anthropic API (cloud) │
|
||
|
|
└─────────────────────────────────────────────────────────────────┘
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 10. Version Compatibility Matrix
|
||
|
|
|
||
|
|
| Component | Required Version | Notes |
|
||
|
|
|-----------|-----------------|-------|
|
||
|
|
| Python | 3.10+ | Type hints, async |
|
||
|
|
| Node.js | 18+ | ES modules |
|
||
|
|
| React | 18+ | Concurrent features |
|
||
|
|
| FastAPI | 0.100+ | Pydantic v2 |
|
||
|
|
| Pydantic | 2.0+ | New validation API |
|
||
|
|
| ReactFlow | 11+ | Custom nodes |
|
||
|
|
| Optuna | 3.0+ | Trial management |
|
||
|
|
| NX | 12+ (tested 2306) | NX Open API |
|
||
|
|
| Claude | claude-3-5-sonnet | Tool use |
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 11. Testing Architecture
|
||
|
|
|
||
|
|
```
|
||
|
|
┌─────────────────────────────────────────────────────────────────┐
|
||
|
|
│ Test Pyramid │
|
||
|
|
└─────────────────────────────────────────────────────────────────┘
|
||
|
|
|
||
|
|
┌─────────────┐
|
||
|
|
│ E2E │ ← Playwright/Cypress
|
||
|
|
│ (few) │ Full user flows
|
||
|
|
└──────┬──────┘
|
||
|
|
│
|
||
|
|
┌────────────┴────────────┐
|
||
|
|
│ │
|
||
|
|
▼ ▼
|
||
|
|
┌─────────────┐ ┌─────────────┐
|
||
|
|
│ Integration │ │ Integration │
|
||
|
|
│ (frontend) │ │ (backend) │
|
||
|
|
└──────┬──────┘ └──────┬──────┘
|
||
|
|
│ │
|
||
|
|
▼ ▼
|
||
|
|
┌─────────────┐ ┌─────────────┐
|
||
|
|
│ Unit │ │ Unit │
|
||
|
|
│ (React) │ │ (Python) │
|
||
|
|
│ Jest/Vitest│ │ pytest │
|
||
|
|
└─────────────┘ └─────────────┘
|
||
|
|
```
|
||
|
|
|
||
|
|
### Test Coverage Goals
|
||
|
|
|
||
|
|
| Layer | Target | Current |
|
||
|
|
|-------|--------|---------|
|
||
|
|
| Unit (Python) | 80% | ~70% |
|
||
|
|
| Unit (React) | 70% | ~50% |
|
||
|
|
| Integration | 60% | ~40% |
|
||
|
|
| E2E | Key flows | Manual |
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Summary
|
||
|
|
|
||
|
|
Atomizer's architecture is built on these core principles:
|
||
|
|
|
||
|
|
1. **Single Source of Truth**: All configuration in `atomizer_spec.json`
|
||
|
|
2. **Type Safety**: Pydantic on backend, TypeScript on frontend
|
||
|
|
3. **Real-time Sync**: WebSocket broadcast for multi-client coordination
|
||
|
|
4. **Optimistic Updates**: Responsive UI with async persistence
|
||
|
|
5. **Modular Engine**: Pluggable extractors, algorithms, surrogates
|
||
|
|
|
||
|
|
The architecture is robust for its intended use case (engineering optimization) and can scale horizontally by:
|
||
|
|
- Adding more backend workers
|
||
|
|
- Sharding studies across directories
|
||
|
|
- Upgrading to distributed database (PostgreSQL)
|
||
|
|
- Adding Redis for session state
|