# 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