# 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. Reference [Design Principles](design-principles.md) for architectural guidelines\n4. Use [System Overview](system-overview.md) for comprehensive system understanding\n\n### For System Operators\n\n1. Focus on [System Overview](system-overview.md) for deployment and operation insights\n2. Review [ADR-002: Distribution Strategy](adr/adr-002-distribution-strategy.md) for deployment patterns\n3. Study [ADR-003: Workspace Isolation](adr/adr-003-workspace-isolation.md) for user management\n4. Reference [Design Principles](design-principles.md) for operational guidelines\n\n## Document Evolution\n\nThese architecture documents are living resources that evolve with the system:\n\n- **ADRs are immutable** once accepted, with new ADRs created for major changes\n- **System documentation is updated** to reflect current architecture\n- **Cross-references are maintained** between related documents\n- **Version compatibility** is documented for architectural changes\n\n## Contributing to Architecture Documentation\n\nWhen making significant architectural changes:\n\n1. **Create new ADRs** for major decisions using the standard format\n2. **Update system documentation** to reflect architectural changes\n3. **Maintain cross-references** between related documents\n4. **Document trade-offs** and alternatives considered\n5. **Update integration patterns** for new architectural patterns\n\n## Architecture Review Process\n\nAll significant architectural changes follow a review process:\n\n1. **Proposal Phase**: Create draft ADR with context and proposed decision\n2. **Review Phase**: Technical review by architecture team and stakeholders\n3. **Decision Phase**: Accept, modify, or reject based on review feedback\n4. **Documentation Phase**: Update related documentation and integration patterns\n5. **Implementation Phase**: Guide implementation according to architectural decisions\n\nThis architecture documentation represents the collective wisdom and experience of building a sophisticated, production-ready infrastructure\nautomation platform.
