# 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