# Design Principles\n\n## Overview\n\nProvisioning is built on a foundation of architectural principles that guide design decisions,\nensure system quality, and maintain consistency across the codebase.\nThese principles have evolved from real-world experience\nand represent lessons learned from complex infrastructure automation challenges.\n\n## Core Architectural Principles\n\n### 1. Project Architecture Principles (PAP) Compliance\n\n**Principle**: Fully agnostic and configuration-driven, not hardcoded. Use abstraction layers dynamically loaded from configurations.\n\n**Rationale**: Infrastructure as Code (IaC) systems must be flexible enough to adapt to any environment\nwithout code changes. Hardcoded values defeat the purpose of IaC and create maintenance burdens.\n\n**Implementation Guidelines**:\n\n- Never patch the system with hardcoded fallbacks when configuration parsing fails\n- All behavior must be configurable through the hierarchical configuration system\n- Use abstraction layers that are dynamically loaded from configuration\n- Validate configuration fully before execution, fail fast on invalid config\n\n**Anti-Patterns (Anti-PAP)**:\n\n- Hardcoded provider endpoints or credentials\n- Environment-specific logic in code\n- Fallback to default values when configuration is missing\n- Mixed configuration and implementation logic\n\n**Example**:\n\n```\n# ✅ PAP Compliant - Configuration-driven\n[providers.aws]\nregions = ["us-west-2", "us-east-1"]\ninstance_types = ["t3.micro", "t3.small"]\napi_endpoint = "https://ec2.amazonaws.com"\n\n# ❌ Anti-PAP - Hardcoded fallback in code\nif config.providers.aws.regions.is_empty() {\n regions = vec!["us-west-2"]; // Hardcoded fallback\n}\n```\n\n### 2. Hybrid Architecture Optimization\n\n**Principle**: Use each language for what it does best - Rust for coordination, Nushell for business logic.\n\n**Rationale**: Different languages have different strengths. Rust excels at performance-critical coordination tasks, while Nushell excels at\nconfiguration management and domain-specific operations.\n\n**Implementation Guidelines**:\n\n- Rust handles orchestration, state management, and performance-critical paths\n- Nushell handles provider operations, configuration processing, and CLI interfaces\n- Clear boundaries between language responsibilities\n- Structured data exchange (JSON) between languages\n- Preserve existing domain expertise in Nushell\n\n**Language Responsibility Matrix**:\n\n```\nRust Layer:\n├── Workflow orchestration and coordination\n├── REST API servers and HTTP endpoints\n├── State persistence and checkpoint management\n├── Parallel processing and batch operations\n├── Error recovery and rollback logic\n└── Performance-critical data processing\n\nNushell Layer:\n├── Provider implementations (AWS, UpCloud, local)\n├── Task service management and configuration\n├── Nickel configuration processing and validation\n├── Template generation and Infrastructure as Code\n├── CLI user interfaces and interactive tools\n└── Domain-specific business logic\n```\n\n### 3. Configuration-First Architecture\n\n**Principle**: All system behavior is determined by configuration, with clear hierarchical precedence and validation.\n\n**Rationale**: True Infrastructure as Code requires that all behavior be configurable without code changes. Configuration hierarchy provides\nflexibility while maintaining predictability.\n\n**Configuration Hierarchy** (precedence order):\n\n1. Runtime Parameters (highest precedence)\n2. Environment Configuration\n3. Infrastructure Configuration\n4. User Configuration\n5. System Defaults (lowest precedence)\n\n**Implementation Guidelines**:\n\n- Complete configuration validation before execution\n- Variable interpolation for dynamic values\n- Schema-based validation using Nickel\n- Configuration immutability during execution\n- Comprehensive error reporting for configuration issues\n\n### 4. Domain-Driven Structure\n\n**Principle**: Organize code by business domains and func
