# ADR-004: Hybrid Architecture\n\n## Status\n\nAccepted\n\n## Context\n\nProvisioning encountered fundamental limitations with a pure Nushell implementation that required architectural solutions:\n\n1. **Deep Call Stack Limitations**: Nushell's `open` command fails in deep call contexts\n (`enumerate | each`), causing "Type not supported" errors in template.nu:71\n2. **Performance Bottlenecks**: Complex workflow orchestration hitting Nushell's performance limits\n3. **Concurrency Constraints**: Limited parallel processing capabilities in Nushell for batch operations\n4. **Integration Complexity**: Need for REST API endpoints and external system integration\n5. **State Management**: Complex state tracking and persistence requirements beyond Nushell's capabilities\n6. **Business Logic Preservation**: 65+ existing Nushell files with domain expertise that shouldn't be rewritten\n7. **Developer Productivity**: Nushell excels for configuration management and domain-specific operations\n\nThe system needed an architecture that:\n\n- Solves Nushell's technical limitations without losing business logic\n- Leverages each language's strengths appropriately\n- Maintains existing investment in Nushell domain knowledge\n- Provides performance for coordination-heavy operations\n- Enables modern integration patterns (REST APIs, async workflows)\n- Preserves configuration-driven, Infrastructure as Code principles\n\n## Decision\n\nImplement a **Hybrid Rust/Nushell Architecture** with clear separation of concerns:\n\n### Architecture Layers\n\n#### 1. Coordination Layer (Rust)\n\n- **Orchestrator**: High-performance workflow coordination and task scheduling\n- **REST API Server**: HTTP endpoints for external integration\n- **State Management**: Persistent state tracking with checkpoint recovery\n- **Batch Processing**: Parallel execution of complex workflows\n- **File-based Persistence**: Lightweight task queue using reliable file storage\n- **Error Recovery**: Sophisticated error handling and rollback capabilities\n\n#### 2. Business Logic Layer (Nushell)\n\n- **Provider Implementations**: Cloud provider-specific operations (AWS, UpCloud, local)\n- **Task Services**: Infrastructure service management (Kubernetes, networking, storage)\n- **Configuration Management**: KCL-based configuration processing and validation\n- **Template Processing**: Infrastructure-as-Code template generation\n- **CLI Interface**: User-facing command-line tools and workflows\n- **Domain Operations**: All business-specific logic and operations\n\n### Integration Patterns\n\n#### Rust → Nushell Communication\n\n```\n// Rust orchestrator invokes Nushell scripts via process execution\nlet result = Command::new("nu")\n .arg("-c")\n .arg("use core/nulib/workflows/server_create.nu *; server_create_workflow 'name' '' []")\n .output()?;\n```\n\n#### Nushell → Rust Communication\n\n```\n# Nushell submits workflows to Rust orchestrator via HTTP API\nhttp post "http://localhost:9090/workflows/servers/create" {\n name: "server-name",\n provider: "upcloud",\n config: $server_config\n}\n```\n\n#### Data Exchange Format\n\n- **Structured JSON**: All data exchange via JSON for type safety and interoperability\n- **Configuration TOML**: Configuration data in TOML format for human readability\n- **State Files**: Lightweight file-based state exchange between layers\n\n### Key Architectural Principles\n\n1. **Language Strengths**: Use each language for what it does best\n2. **Business Logic Preservation**: All existing domain knowledge stays in Nushell\n3. **Performance Critical Path**: Coordination and orchestration in Rust\n4. **Clear Boundaries**: Well-defined interfaces between layers\n5. **Configuration Driven**: Both layers respect configuration-driven architecture\n6. **Error Handling**: Coordinated error handling across language boundaries\n7. **State Consistency**: Consistent state management across hybrid system\n\n## Consequences\n\n### Positive\n\n- **Technical Limitations Solved**: Eliminates Nushell deep call stack issues\n- **Performance Optim
