# Architecture Documentation\n\nThis directory contains comprehensive architecture documentation for provisioning, including Architecture Decision Records (ADRs) and system design\ndocumentation.\n\n## Architecture Decision Records (ADRs)\n\nADRs document the major architectural decisions made for the system, including context, rationale, and consequences:\n\n- **[ADR-001: Project Structure Decision](adr/adr-001-project-structure.md)** - Domain-driven hybrid structure organization\n- **[ADR-002: Distribution Strategy](adr/adr-002-distribution-strategy.md)** - Layered distribution with workspace separation\n- **[ADR-003: Workspace Isolation](adr/adr-003-workspace-isolation.md)** - Isolated user workspaces with hierarchical configuration\n- **[ADR-004: Hybrid Architecture](adr/adr-004-hybrid-architecture.md)** - Rust coordination layer with Nushell business logic\n- **[ADR-005: Extension Framework](adr/adr-005-extension-framework.md)** - Registry-based extension system with manifest-driven loading\n\n## System Design Documentation\n\nComprehensive documentation covering system architecture, integration patterns, and design principles:\n\n### [System Overview](system-overview.md)\n\nHigh-level architecture overview including:\n\n- Executive summary and key achievements\n- Component architecture with diagrams\n- Technology stack and dependencies\n- Performance and scalability characteristics\n- Security architecture and quality attributes\n\n### [Integration Patterns](integration-patterns.md)\n\nDetailed integration patterns and implementations:\n\n- Hybrid language integration (Rust ↔ Nushell)\n- Provider abstraction and multi-cloud support\n- Configuration resolution and variable interpolation\n- Workflow orchestration and dependency management\n- State management and checkpoint recovery\n- Event-driven architecture and messaging\n- Extension integration and API patterns\n- Error handling and performance optimization\n\n### [Design Principles](design-principles.md)\n\nCore architectural principles and guidelines:\n\n- Project Architecture Principles (PAP) compliance\n- Hybrid architecture optimization strategies\n- Configuration-first architecture approach\n- Domain-driven structural organization\n- Quality attribute principles (reliability, performance, security)\n- Error handling and observability principles\n- Evolution and maintenance strategies\n\n## Key Architectural Achievements\n\n### 🚀 Batch Workflow System (v3.1.0)\n\n- **Provider-Agnostic Design**: Mixed UpCloud, AWS, and local provider support\n- **Advanced Orchestration**: Dependency resolution, parallel execution, and rollback capabilities\n- **Real-time Monitoring**: Live workflow progress tracking and health monitoring\n\n### 🏗️ Hybrid Orchestrator Architecture (v3.0.0)\n\n- **Performance Solution**: Solves Nushell deep call stack limitations\n- **Business Logic Preservation**: 65+ Nushell files with domain expertise maintained\n- **REST API Integration**: Modern HTTP endpoints for external system integration\n- **State Management**: Checkpoint-based recovery with comprehensive rollback\n\n### ⚙️ Configuration System (v2.0.0)\n\n- **Configuration Migration**: Systematic migration from ENV variables to configuration files\n- **Hierarchical Configuration**: Complete configuration flexibility with clear precedence\n- **Variable Interpolation**: Dynamic configuration with runtime variable resolution\n- **PAP Compliance**: True Infrastructure as Code without hardcoded fallbacks\n\n## Reading Guide\n\n### For New Developers\n\n1. Start with [System Overview](system-overview.md) for high-level understanding\n2. Read [Design Principles](design-principles.md) to understand architectural philosophy\n3. Review relevant ADRs for specific architectural decisions\n4. Study [Integration Patterns](integration-patterns.md) for implementation details\n\n### For Architects and Senior Developers\n\n1. Review all ADRs to understand decision rationale and trade-offs\n2. Study [Integration Patterns](integration-patterns.md) for advanced implementation patterns\n3.
