# Provider-Agnostic Architecture Documentation\n\n## Overview\n\nThe new provider-agnostic architecture eliminates hardcoded provider dependencies and enables true multi-provider infrastructure deployments. This\naddresses two critical limitations of the previous middleware:\n\n1. **Hardcoded provider dependencies** - No longer requires importing specific provider modules\n2. **Single-provider limitation** - Now supports mixing multiple providers in the same deployment (for example, AWS compute + Cloudflare DNS + UpCloud\nbackup)\n\n## Architecture Components\n\n### 1. Provider Interface (`interface.nu`)\n\nDefines the contract that all providers must implement:\n\n```\n# Standard interface functions\n- query_servers\n- server_info\n- server_exists\n- create_server\n- delete_server\n- server_state\n- get_ip\n# ... and 20+ other functions\n```\n\n**Key Features:**\n\n- Type-safe function signatures\n- Comprehensive validation\n- Provider capability flags\n- Interface versioning\n\n### 2. Provider Registry (`registry.nu`)\n\nManages provider discovery and registration:\n\n```\n# Initialize registry\ninit-provider-registry\n\n# List available providers\nlist-providers --available-only\n\n# Check provider availability\nis-provider-available "aws"\n```\n\n**Features:**\n\n- Automatic provider discovery\n- Core and extension provider support\n- Caching for performance\n- Provider capability tracking\n\n### 3. Provider Loader (`loader.nu`)\n\nHandles dynamic provider loading and validation:\n\n```\n# Load provider dynamically\nload-provider "aws"\n\n# Get provider with auto-loading\nget-provider "upcloud"\n\n# Call provider function\ncall-provider-function "aws" "query_servers" $find $cols\n```\n\n**Features:**\n\n- Lazy loading (load only when needed)\n- Interface compliance validation\n- Error handling and recovery\n- Provider health checking\n\n### 4. Provider Adapters\n\nEach provider implements a standard adapter:\n\n```\nprovisioning/extensions/providers/\n├── aws/provider.nu        # AWS adapter\n├── upcloud/provider.nu    # UpCloud adapter\n├── local/provider.nu      # Local adapter\n└── {custom}/provider.nu   # Custom providers\n```\n\n**Adapter Structure:**\n\n```\n# AWS Provider Adapter\nexport def query_servers [find?: string, cols?: string] {\n    aws_query_servers $find $cols\n}\n\nexport def create_server [settings: record, server: record, check: bool, wait: bool] {\n    # AWS-specific implementation\n}\n```\n\n### 5. Provider-Agnostic Middleware (`middleware_provider_agnostic.nu`)\n\nThe new middleware that uses dynamic dispatch:\n\n```\n# No hardcoded imports!\nexport def mw_query_servers [settings: record, find?: string, cols?: string] {\n    $settings.data.servers | each { |server|\n        # Dynamic provider loading and dispatch\n        dispatch_provider_function $server.provider "query_servers" $find $cols\n    }\n}\n```\n\n## Multi-Provider Support\n\n### Example: Mixed Provider Infrastructure\n\n```\nlet servers = [\n    {\n        hostname = "compute-01",\n        provider = "aws",\n        # AWS-specific config\n    },\n    {\n        hostname = "backup-01",\n        provider = "upcloud",\n        # UpCloud-specific config\n    },\n    {\n        hostname = "api.example.com",\n        provider = "cloudflare",\n        # DNS-specific config\n    },\n] in\nservers\n```\n\n### Multi-Provider Deployment\n\n```\n# Deploy across multiple providers automatically\nmw_deploy_multi_provider_infra $settings $deployment_plan\n\n# Get deployment strategy recommendations\nmw_suggest_deployment_strategy {\n    regions: ["us-east-1", "eu-west-1"]\n    high_availability: true\n    cost_optimization: true\n}\n```\n\n## Provider Capabilities\n\nProviders declare their capabilities:\n\n```\ncapabilities: {\n    server_management: true\n    network_management: true\n    auto_scaling: true        # AWS: yes, Local: no\n    multi_region: true        # AWS: yes, Local: no\n    serverless: true          # AWS: yes, UpCloud: no\n    compliance_certifications: ["SOC2", "HIPAA"]\n}\n```\n\n## Migration Guide\n\n### From Old Middleware\n\n**Before (hardcoded):**\n\n```\n# middleware.nu\nuse ../aws/nulib/aws/servers.nu *\nuse ../upcloud/nulib/upcloud/servers.nu *\n\nmatch $server.provider {\n    "aws" => { aws_query_servers $find $cols }\n    "upcloud" => { upcloud_query_servers $find $cols }\n}\n```\n\n**After (provider-agnostic):**\n\n```\n# middleware_provider_agnostic.nu\n# No hardcoded imports!\n\n# Dynamic dispatch\ndispatch_provider_function $server.provider "query_servers" $find $cols\n```\n\n### Migration Steps\n\n1. **Replace middleware file:**\n\n   ```bash\n   cp provisioning/extensions/providers/prov_lib/middleware.nu \\n      provisioning/extensions/providers/prov_lib/middleware_legacy.backup\n\n   cp provisioning/extensions/providers/prov_lib/middleware_provider_agnostic.nu \\n      provisioning/extensions/providers/prov_lib/middleware.nu\n   ```\n\n1. **Test with existing infrastructure:**\n\n   ```nushell\n   ./provisioning/tools/test-provider-agnostic.nu run-all-tests\n   ```\n\n2. **Update any custom code** that directly imported provider modules\n\n## Adding New Providers\n\n### 1. Create Provider Adapter\n\nCreate `provisioning/extensions/providers/{name}/provider.nu`:\n\n```\n# Digital Ocean Provider Example\nexport def get-provider-metadata [] {\n    {\n        name: "digitalocean"\n        version: "1.0.0"\n        capabilities: {\n            server_management: true\n            # ... other capabilities\n        }\n    }\n}\n\n# Implement required interface functions\nexport def query_servers [find?: string, cols?: string] {\n    # DigitalOcean-specific implementation\n}\n\nexport def create_server [settings: record, server: record, check: bool, wait: bool] {\n    # DigitalOcean-specific implementation\n}\n\n# ... implement all required functions\n```\n\n### 2. Provider Discovery\n\nThe registry will automatically discover the new provider on next initialization.\n\n### 3. Test New Provider\n\n```\n# Check if discovered\nis-provider-available "digitalocean"\n\n# Load and test\nload-provider "digitalocean"\ncheck-provider-health "digitalocean"\n```\n\n## Best Practices\n\n### Provider Development\n\n1. **Implement full interface** - All functions must be implemented\n2. **Handle errors gracefully** - Return appropriate error values\n3. **Follow naming conventions** - Use consistent function naming\n4. **Document capabilities** - Accurately declare what your provider supports\n5. **Test thoroughly** - Validate against the interface specification\n\n### Multi-Provider Deployments\n\n1. **Use capability-based selection** - Choose providers based on required features\n2. **Handle provider failures** - Design for provider unavailability\n3. **Optimize for cost/performance** - Mix providers strategically\n4. **Monitor cross-provider dependencies** - Understand inter-provider communication\n\n### Profile-Based Security\n\n```\n# Environment profiles can restrict providers\nPROVISIONING_PROFILE=production  # Only allows certified providers\nPROVISIONING_PROFILE=development # Allows all providers including local\n```\n\n## Troubleshooting\n\n### Common Issues\n\n1. **Provider not found**\n   - Check provider is in correct directory\n   - Verify provider.nu exists and implements interface\n   - Run `init-provider-registry` to refresh\n\n2. **Interface validation failed**\n   - Use `validate-provider-interface` to check compliance\n   - Ensure all required functions are implemented\n   - Check function signatures match interface\n\n3. **Provider loading errors**\n   - Check Nushell module syntax\n   - Verify import paths are correct\n   - Use `check-provider-health` for diagnostics\n\n### Debug Commands\n\n```\n# Registry diagnostics\nget-provider-stats\nlist-providers --verbose\n\n# Provider diagnostics\ncheck-provider-health "aws"\ncheck-all-providers-health\n\n# Loader diagnostics\nget-loader-stats\n```\n\n## Performance Benefits\n\n1. **Lazy Loading** - Providers loaded only when needed\n2. **Caching** - Provider registry cached to disk\n3. **Reduced Memory** - No hardcoded imports reducing memory usage\n4. **Parallel Operations** - Multi-provider operations can run in parallel\n\n## Future Enhancements\n\n1. **Provider Plugins** - Support for external provider plugins\n2. **Provider Versioning** - Multiple versions of same provider\n3. **Provider Composition** - Compose providers for complex scenarios\n4. **Provider Marketplace** - Community provider sharing\n\n## API Reference\n\nSee the interface specification for complete function documentation:\n\n```\nget-provider-interface-docs | table\n```\n\nThis returns the complete API with signatures and descriptions for all provider interface functions.
