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:
144
docs/diagrams/00_INDEX.md
Normal file
144
docs/diagrams/00_INDEX.md
Normal file
@@ -0,0 +1,144 @@
|
||||
# Atomizer Diagrams Index
|
||||
|
||||
**Last Updated**: 2025-11-21
|
||||
**Purpose**: Visual documentation of Atomizer's architecture, workflows, and protocols
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
This directory contains comprehensive visual documentation using Mermaid diagrams. These diagrams are designed to be:
|
||||
- **Rendered automatically** in GitHub, VS Code, and documentation sites
|
||||
- **Easy to maintain** as plain text with version control
|
||||
- **Comprehensive** covering architecture, workflows, and protocol details
|
||||
|
||||
---
|
||||
|
||||
## Available Diagrams
|
||||
|
||||
### 1. System Architecture
|
||||
**File**: [architecture_overview.md](architecture_overview.md)
|
||||
|
||||
Complete system architecture showing:
|
||||
- Core components and their relationships
|
||||
- Data flow between optimization engine, NX solver, and dashboard
|
||||
- Plugin system and extensibility points
|
||||
- Protocol integration layers
|
||||
|
||||
### 2. Protocol Workflows
|
||||
**File**: [protocol_workflows.md](protocol_workflows.md)
|
||||
|
||||
Detailed protocol execution flows:
|
||||
- Protocol 10: Intelligent Multi-Strategy Optimization (IMSO)
|
||||
- Protocol 11: Multi-Objective Support
|
||||
- Protocol 13: Real-Time Dashboard Tracking
|
||||
- LLM-assisted optimization workflow (Hybrid Mode)
|
||||
|
||||
### 3. Optimization Lifecycle
|
||||
**File**: [optimization_lifecycle.md](optimization_lifecycle.md)
|
||||
|
||||
Trial-by-trial execution flow:
|
||||
- Study initialization
|
||||
- Design variable sampling
|
||||
- NX model update and solving
|
||||
- Result extraction and objective calculation
|
||||
- Optuna feedback loop
|
||||
|
||||
---
|
||||
|
||||
## Viewing Diagrams
|
||||
|
||||
### GitHub
|
||||
Diagrams render automatically when viewing `.md` files on GitHub.
|
||||
|
||||
### VS Code
|
||||
Install the **Markdown Preview Mermaid Support** extension:
|
||||
```
|
||||
code --install-extension bierner.markdown-mermaid
|
||||
```
|
||||
|
||||
### Documentation Sites
|
||||
Mermaid diagrams are supported by:
|
||||
- MkDocs (with pymdown-extensions)
|
||||
- Docusaurus
|
||||
- GitBook
|
||||
- Most modern documentation generators
|
||||
|
||||
### Online Viewer
|
||||
Copy diagram code to: https://mermaid.live/
|
||||
|
||||
---
|
||||
|
||||
## Diagram Conventions
|
||||
|
||||
### Color Coding
|
||||
- **Blue (#4A90E2)**: Core optimization components
|
||||
- **Green (#7CB342)**: NX/Solver integration
|
||||
- **Orange (#FF9800)**: Dashboard/Tracking
|
||||
- **Purple (#9C27B0)**: Protocol logic
|
||||
- **Red (#E53935)**: LLM/Hybrid features
|
||||
- **Gray (#757575)**: Data/Configuration
|
||||
|
||||
### Node Shapes
|
||||
- **Rectangles**: Processes/Components
|
||||
- **Rounded Rectangles**: Modules/Systems
|
||||
- **Diamonds**: Decision points
|
||||
- **Cylinders**: Databases/Storage
|
||||
- **Circles**: Entry/Exit points
|
||||
|
||||
### Arrow Types
|
||||
- **Solid arrow (→)**: Data flow
|
||||
- **Dashed arrow (-->)**: Control flow
|
||||
- **Thick arrow (==>)**: Critical path
|
||||
- **Dotted arrow (-.)**: Optional/Conditional
|
||||
|
||||
---
|
||||
|
||||
## Maintenance
|
||||
|
||||
### Updating Diagrams
|
||||
|
||||
When code changes affect architecture:
|
||||
1. Update relevant diagram file
|
||||
2. Test rendering in VS Code or GitHub preview
|
||||
3. Update "Last Updated" date in diagram header
|
||||
4. Commit with descriptive message: `docs: Update architecture diagram for [feature]`
|
||||
|
||||
### Creating New Diagrams
|
||||
|
||||
For new features or protocols:
|
||||
1. Create new `.md` file in this directory
|
||||
2. Use existing diagrams as templates
|
||||
3. Follow naming convention: `feature_name.md`
|
||||
4. Add entry to this index
|
||||
5. Link from relevant protocol documentation
|
||||
|
||||
### Testing Diagrams
|
||||
|
||||
Before committing:
|
||||
```bash
|
||||
# Check syntax with Mermaid CLI (if installed)
|
||||
mmdc -i diagram.md -o test.svg
|
||||
|
||||
# Or test in browser
|
||||
# Copy code to https://mermaid.live/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Links
|
||||
|
||||
### Documentation
|
||||
- [Main Index](../00_INDEX.md)
|
||||
- [Protocols](../01_PROTOCOLS.md)
|
||||
- [Architecture](../02_ARCHITECTURE.md)
|
||||
|
||||
### Implementation
|
||||
- [Optimization Engine](../../optimization_engine/)
|
||||
- [NX Integration](../../nx_journals/)
|
||||
- [Dashboard](../../atomizer-dashboard/)
|
||||
|
||||
---
|
||||
|
||||
**Maintained By**: Atomizer Development Team
|
||||
**Feedback**: Open GitHub issue with "documentation" label
|
||||
Reference in New Issue
Block a user