docs: Major documentation overhaul - restructure folders, update tagline, add Getting Started guide
- 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
This commit is contained in:
529
docs/reviews/COMPONENT_RELATIONSHIPS.md
Normal file
529
docs/reviews/COMPONENT_RELATIONSHIPS.md
Normal file
@@ -0,0 +1,529 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user