Anto01
ea437d360e
- Restructure docs/ folder (remove numeric prefixes): - 04_USER_GUIDES -> guides/ - 05_API_REFERENCE -> api/ - 06_PHYSICS -> physics/ - 07_DEVELOPMENT -> development/ - 08_ARCHIVE -> archive/ - 09_DIAGRAMS -> diagrams/ - Replace tagline 'Talk, don't click' with 'LLM-driven optimization framework' in 9 files - Create comprehensive docs/GETTING_STARTED.md: - Prerequisites and quick setup - Project structure overview - First study tutorial (Claude or manual) - Dashboard usage guide - Neural acceleration introduction - Rewrite docs/00_INDEX.md with correct paths and modern structure - Archive obsolete files: - 01_PROTOCOLS.md -> archive/historical/01_PROTOCOLS_legacy.md - 03_GETTING_STARTED.md -> archive/historical/ - ATOMIZER_PODCAST_BRIEFING.md -> archive/marketing/ - Update timestamps to 2026-01-20 across all key files - Update .gitignore to exclude docs/generated/ - Version bump: ATOMIZER_CONTEXT v1.8 -> v2.0
27 KiB
27 KiB
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
- User edits node →
useSpecStore.patchSpec(path, value) - Optimistic update → UI immediately reflects change
- Async PATCH → Backend validates and saves
- WebSocket broadcast → All clients receive
spec_updated - 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:
- Single Source of Truth: All configuration in
atomizer_spec.json - Type Safety: Pydantic on backend, TypeScript on frontend
- Real-time Sync: WebSocket broadcast for multi-client coordination
- Optimistic Updates: Responsive UI with async persistence
- 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