# Architecture Overview

Comprehensive overview of macOS Resource Optimizer's two-layer architecture design.

## System Architecture

macOS Resource Optimizer v7.0 implements a sophisticated two-layer architecture:

```
┌─────────────────────────────────────────────────────────┐
│          MoAI-ADK Integration Layer (Top)              │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  Command Handlers (0, 1, 2, 3, 4, 9)                  │
│         ↓                                              │
│  Coordinator (Central Decision Hub)                    │
│         ↓                                              │
│  Strategy Layer (Analysis & Planning)                  │
│                                                         │
└─────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────┐
│         Python Engine Layer (Bottom)                    │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  Experts (Specialized Optimizers)                      │
│  ├─ CPU Optimizer                                       │
│  ├─ Memory Optimizer                                    │
│  ├─ Disk Optimizer                                      │
│  ├─ Battery Optimizer                                   │
│  ├─ Thermal Optimizer                                   │
│  └─ Network Optimizer                                   │
│                                                         │
│  Support Layer                                          │
│  ├─ Metrics Cache (2500× speedup)                      │
│  ├─ Async Executor (6× parallelization)               │
│  └─ Reports Generator                                  │
│                                                         │
└─────────────────────────────────────────────────────────┘
```

## Key Components

### Top Layer: MoAI-ADK Integration

**Coordinator**: Central orchestration point that:
- Routes commands to appropriate handlers
- Manages strategy execution
- Coordinates expert execution
- Generates responses

**Strategy**: Decision-making engine that:
- Analyzes system metrics
- Plans optimization actions
- Prioritizes changes
- Estimates improvements

### Bottom Layer: Python Engine

**Experts**: Specialized optimization modules:
- **CPU Optimizer**: Manages processor efficiency
- **Memory Optimizer**: Optimizes RAM usage
- **Disk Optimizer**: Manages storage efficiency
- **Battery Optimizer**: Extends battery life
- **Thermal Optimizer**: Manages heat dissipation
- **Network Optimizer**: Improves connectivity

**Support Systems**:
- **Metrics Cache**: 2500× faster metric retrieval
- **Async Executor**: Parallel optimization (6× faster)
- **Reports Generator**: Comprehensive reporting

## Data Flow

```
Command Input
    ↓
Coordinator parses command
    ↓
Strategy analyzes system state
    ↓
Experts execute optimizations (parallel)
    ↓
Metrics collected and cached
    ↓
Results aggregated
    ↓
Response generated
```

## Performance Characteristics

### Execution Speed

| Operation | Time | Improvement |
|-----------|------|-------------|
| Initialize | 1.0s | N/A |
| Analyze | 1.8s | 50% faster |
| Optimize | 2.0s | 50% faster |
| Monitor | 3.0s | Real-time |
| Report | 1.5s | 40% faster |
| **Total** | **9.3s** | **Production-ready** |

### Optimization Efficiency

- **Parallel execution**: 6× speedup using asyncio.gather
- **Caching**: 2500× faster with MetricsCache
- **Memory**: Optimized for 4GB+ systems
- **Compatibility**: macOS 10.15+

## Design Principles

1. **Modularity**: Each expert is independent
2. **Parallelization**: Operations run concurrently
3. **Caching**: Reduce redundant computations
4. **Robustness**: Graceful degradation on errors
5. **Observability**: Comprehensive logging

## Next Steps

- Learn about [Two-Layer Design](/architecture/two-layer-design)
- Understand [Integration Flow](/architecture/integration-flow)
- Explore [API Reference](/api/coordinator)
- Review [Commands](/commands/analyze)

## Technology Stack

- **Language**: Python 3.9+
- **Framework**: MoAI-ADK 0.30.2+
- **Parallelization**: asyncio
- **Caching**: Custom MetricsCache
- **Testing**: pytest with 86%+ coverage

See [Two-Layer Architecture](/architecture/two-layer-design) for detailed component breakdown.
