\n 
\n
\n
\n 
\n
\n\n# Provisioning Platform Documentation\n\n**Last Updated**: 2025-01-02 (Phase 3.A Cleanup Complete)\n**Status**:
✅ Primary documentation source (145 files consolidated)\n\nWelcome to the comprehensive documentation for the Provisioning Platform - a modern, cloud-native infrastructure automation system built with Nushell,\nNickel, and Rust.\n\n> **Note**: Architecture Decision Records (ADRs) and design documentation are in `docs/`\n> directory. This location contains user-facing, operational, and product documentation.\n\n---\n\n## Quick Navigation\n\n###
🚀 Getting Started\n\n| Document | Description | Audience |\n| ---------- | ------------- | ---------- |\n| **[Installation Guide](getting-started/installation-guide.md)** | Install and configure the system | New Users |\n| **[Getting Started](getting-started/getting-started.md)** | First steps and basic concepts | New Users |\n| **[Quick Reference](getting-started/quickstart-cheatsheet.md)** | Command cheat sheet | All Users |\n| **[From Scratch Guide](guides/from-scratch.md)** | Complete deployment walkthrough | New Users |\n\n###
📚 User Guides\n\n| Document | Description |\n| ---------- | ------------- |\n| **[CLI Reference](infrastructure/cli-reference.md)** | Complete command reference |\n| **[Workspace Management](infrastructure/workspace-setup.md)** | Workspace creation and management |\n| **[Workspace Switching](infrastructure/workspace-switching-guide.md)** | Switch between workspaces |\n| **[Infrastructure Management](infrastructure/infrastructure-management.md)** | Server, taskserv, cluster operations |\n| **[Service Management](operations/service-management-guide.md)** | Platform service lifecycle management |\n| **[OCI Registry](integration/oci-registry-guide.md)** | OCI artifact management |\n| **[Gitea Integration](integration/gitea-integration-guide.md)** | Git workflow and collaboration |\n| **[CoreDNS Guide](operations/coredns-guide.md)** | DNS management |\n| **[Test Environments](testing/test-environment-usage.md)** | Containerized testing |\n| **[Extension Development](development/extension-development.md)** | Create custom extensions |\n\n###
🏗️ Architecture\n\n| Document | Description |\n| ---------- | ------------- |\n| **[System Overview](architecture/system-overview.md)** | High-level architecture |\n| **[Multi-Repo Architecture](architecture/multi-repo-architecture.md)** | Repository structure and OCI distribution |\n| **[Design Principles](architecture/design-principles.md)** | Architectural philosophy |\n| **[Integration Patterns](architecture/integration-patterns.md)** | System integration patterns |\n| **[Orchestrator Model](architecture/orchestrator-integration-model.md)** | Hybrid orchestration architecture |\n\n###
📋 Architecture Decision Records (ADRs)\n\n| ADR | Title | Status |\n| ----- | ------- | -------- |\n| **[ADR-001](architecture/adr/adr-001-project-structure.md)** | Project Structure Decision | Accepted |\n| **[ADR-002](architecture/adr/adr-002-distribution-strategy.md)** | Distribution Strategy | Accepted |\n| **[ADR-003](architecture/adr/adr-003-workspace-isolation.md)** | Workspace Isolation | Accepted |\n| **[ADR-004](architecture/adr/adr-004-hybrid-architecture.md)** | Hybrid Architecture | Accepted |\n| **[ADR-005](architecture/adr/adr-005-extension-framework.md)** | Extension Framework | Accepted |\n| **[ADR-006](architecture/adr/adr-006-provisioning-cli-refactoring.md)** | CLI Refactoring | Accepted |\n\n###
🔌 API Documentation\n\n| Document | Description |\n| ---------- | ------------- |\n| **[REST API](api-reference/rest-api.md)** | HTTP API endpoints |\n| **[WebSocket API](api-reference/websocket.md)** | Real-time event streams |\n| **[Extensions API](development/extensions.md)** | Extension integration APIs |\n| **[SDKs](api-reference/sdks.md)** | Client libraries |\n| **[Integration Examples](api-reference/integration-examples.md)** | API usage examples |\n\n###
🛠️ Development\n\n| Document | Description |\n| ---------- | ------------- |\n| **[Development README](development/README.md)** | Developer overview |\n| **[Implementation Guide](development/implementation-guide.md)** | Implementation details |\n| **[Provider Development](development/quick-provider-guide.md)** | Create cloud providers |\n| **[Taskserv Development](development/taskserv-developer-guide.md)** | Create task services |\n| **[Extension Framework](development/extensions.md)** | Extension system |\n| **[Command Handlers](development/command-handler-guide.md)** | CLI command development |\n\n###
🐛 Troubleshooting\n\n| Document | Description |\n| ---------- | ------------- |\n| **[Troubleshooting Guide](troubleshooting/troubleshooting-guide.md)** | Common issues and solutions |\n\n###
📖 How-To Guides\n\n| Document | Description |\n| ---------- | ------------- |\n| **[From Scratch](guides/from-scratch.md)** | Complete deployment from zero |\n| **[Update Infrastructure](guides/update-infrastructure.md)** | Safe update procedures |\n| **[Customize Infrastructure](guides/customize-infrastructure.md)** | Layer and template customization |\n\n###
🔐 Configuration\n\n| Document | Description |\n| ---------- | ------------- |\n| **[Workspace Config Architecture](configuration/workspace-config-architecture.md)** | Configuration architecture |\n\n###
📦 Quick References\n\n| Document | Description |\n| ---------- | ------------- |\n| **[Quickstart Cheatsheet](getting-started/quickstart-cheatsheet.md)** | Command shortcuts |\n| **[OCI Quick Reference](quick-reference/oci.md)** | OCI operations |\n\n---\n\n## Documentation Structure\n\n```text\nprovisioning/docs/src/\n├── README.md (this file) # Documentation hub\n├── getting-started/ # Getting started guides\n│ ├── installation-guide.md\n│ ├── getting-started.md\n│ └── quickstart-cheatsheet.md\n├── architecture/ # System architecture\n│ ├── adr/ # Architecture Decision Records\n│ ├── design-principles.md\n│ ├── integration-patterns.md\n│ ├── system-overview.md\n│ └── ... (and 10+ more architecture docs)\n├── infrastructure/ # Infrastructure guides\n│ ├── cli-reference.md\n│ ├── workspace-setup.md\n│ ├── workspace-switching-guide.md\n│ └── infrastructure-management.md\n├── api-reference/ # API documentation\n│ ├── rest-api.md\n│ ├── websocket.md\n│ ├── integration-examples.md\n│ └── sdks.md\n├── development/ # Developer guides\n│ ├── README.md\n│ ├── implementation-guide.md\n│ ├── quick-provider-guide.md\n│ ├── taskserv-developer-guide.md\n│ └── ... (15+ more developer docs)\n├── guides/ # How-to guides\n│ ├── from-scratch.md\n│ ├── update-infrastructure.md\n│ └── customize-infrastructure.md\n├── operations/ # Operations guides\n│ ├── service-management-guide.md\n│ ├── coredns-guide.md\n│ └── ... (more operations docs)\n├── security/ # Security docs\n├── integration/ # Integration guides\n├── testing/ # Testing docs\n├── configuration/ # Configuration docs\n├── troubleshooting/ # Troubleshooting guides\n└── quick-reference/ # Quick references\n```\n\n---\n\n## Key Concepts\n\n### Infrastructure as Code (IaC)\n\nThe provisioning platform uses **declarative configuration** to manage infrastructure. Instead of manually creating resources, you define what you\nwant in Nickel configuration files, and the system makes it happen.\n\n### Mode-Based Architecture\n\nThe system supports four operational modes:\n\n- **Solo**: Single developer local development\n- **Multi-user**: Team collaboration with shared services\n- **CI/CD**: Automated pipeline execution\n- **Enterprise**: Production deployment with strict compliance\n\n### Extension System\n\nExtensibility through:\n\n- **Providers**: Cloud platform integrations (AWS, UpCloud, Local)\n- **Task Services**: Infrastructure components (Kubernetes, databases, etc.)\n- **Clusters**: Complete deployment configurations\n\n### OCI-Native Distribution\n\nExtensions and packages distributed as OCI artifacts, enabling:\n\n- Industry-standard packaging\n- Efficient caching and bandwidth\n- Version pinning and rollback\n- Air-gapped deployments\n\n---\n\n## Documentation by Role\n\n### For New Users\n\n1. Start with **[Installation Guide](getting-started/installation-guide.md)**\n2. Read **[Getting Started](getting-started/getting-started.md)**\n3. Follow **[From Scratch Guide](guides/from-scratch.md)**\n4. Reference **[Quickstart Cheatsheet](guides/quickstart-cheatsheet.md)**\n\n### For Developers\n\n1. Review **[System Overview](architecture/system-overview.md)**\n2. Study **[Design Principles](architecture/design-principles.md)**\n3. Read relevant **[ADRs](architecture/)**\n4. Follow **[Development Guide](development/README.md)**\n5. Reference **Nickel Quick Reference**\n\n### For Operators\n\n1. Understand **[Mode System](infrastructure/mode-system)**\n2. Learn **[Service Management](operations/service-management-guide.md)**\n3. Review **[Infrastructure Management](infrastructure/infrastructure-management.md)**\n4. Study **[OCI Registry](integration/oci-registry-guide.md)**\n\n### For Architects\n\n1. Read **[System Overview](architecture/system-overview.md)**\n2. Study all **[ADRs](architecture/)**\n3. Review **[Integration Patterns](architecture/integration-patterns.md)**\n4. Understand **[Multi-Repo Architecture](architecture/multi-repo-architecture.md)**\n\n---\n\n## System Capabilities\n\n###
✅ Infrastructure Automation\n\n- Multi-cloud support (AWS, UpCloud, Local)\n- Declarative configuration with Nickel\n- Automated dependency resolution\n- Batch operations with rollback\n\n###
✅ Workflow Orchestration\n\n- Hybrid Rust/Nushell orchestration\n- Checkpoint-based recovery\n- Parallel execution with limits\n- Real-time monitoring\n\n###
✅ Test Environments\n\n- Containerized testing\n- Multi-node cluster simulation\n- Topology templates\n- Automated cleanup\n\n###
✅ Mode-Based Operation\n\n- Solo: Local development\n- Multi-user: Team collaboration\n- CI/CD: Automated pipelines\n- Enterprise: Production deployment\n\n###
✅ Extension Management\n\n- OCI-native distribution\n- Automatic dependency resolution\n- Version management\n- Local and remote sources\n\n---\n\n## Key Achievements\n\n###
🚀 Batch Workflow System (v3.1.0)\n\n- Provider-agnostic batch operations\n- Mixed provider support (UpCloud + AWS + local)\n- Dependency resolution with soft/hard dependencies\n- Real-time monitoring and rollback\n\n###
🏗️ Hybrid Orchestrator (v3.0.0)\n\n- Solves Nushell deep call stack limitations\n- Preserves all business logic\n- REST API for external integration\n- Checkpoint-based state management\n\n###
⚙️ Configuration System (v2.0.0)\n\n- Migrated from ENV to config-driven\n- Hierarchical configuration loading\n- Variable interpolation\n- True IaC without hardcoded fallbacks\n\n###
🎯 Modular CLI (v3.2.0)\n\n- 84% reduction in main file size\n- Domain-driven handlers\n- 80+ shortcuts\n- Bi-directional help system\n\n###
🧪 Test Environment Service (v3.4.0)\n\n- Automated containerized testing\n- Multi-node cluster topologies\n- CI/CD integration ready\n- Template-based configurations\n\n###
🔄 Workspace Switching (v2.0.5)\n\n- Centralized workspace management\n- Single-command workspace switching\n- Active workspace tracking\n- User preference system\n\n---\n\n## Technology Stack\n\n| Component | Technology | Purpose |\n| ----------- | ------------ | --------- |\n| **Core CLI** | Nushell 0.107.1 | Shell and scripting |\n| **Configuration** | Nickel 1.0.0+ | Type-safe IaC |\n| **Orchestrator** | Rust | High-performance coordination |\n| **Templates** | Jinja2 (nu_plugin_tera) | Code generation |\n| **Secrets** | SOPS 3.10.2 + Age 1.2.1 | Encryption |\n| **Distribution** | OCI (skopeo/crane/oras) | Artifact management |\n\n---\n\n## Support\n\n### Getting Help\n\n- **Documentation**: You're reading it!\n- **Quick Reference**: Run `provisioning sc` or `provisioning guide quickstart`\n- **Help System**: Run `provisioning help` or `provisioning help`\n- **Interactive Shell**: Run `provisioning nu` for Nushell REPL\n\n### Reporting Issues\n\n- Check **[Troubleshooting Guide](infrastructure/troubleshooting-guide.md)**\n- Review **[FAQ](troubleshooting/troubleshooting-guide.md)**\n- Enable debug mode: `provisioning --debug `\n- Check logs: `provisioning platform logs `\n\n---\n\n## Contributing\n\nThis project welcomes contributions! See **[Development Guide](development/README.md)** for:\n\n- Development setup\n- Code style guidelines\n- Testing requirements\n- Pull request process\n\n---\n\n## License\n\n[Add license information]\n\n---\n\n## Version History\n\n| Version | Date | Major Changes |\n| --------- | ------ | --------------- |\n| **3.5.0** | 2025-10-06 | Mode system, OCI registry, comprehensive documentation |\n| **3.4.0** | 2025-10-06 | Test environment service |\n| **3.3.0** | 2025-09-30 | Interactive guides system |\n| **3.2.0** | 2025-09-30 | Modular CLI refactoring |\n| **3.1.0** | 2025-09-25 | Batch workflow system |\n| **3.0.0** | 2025-09-25 | Hybrid orchestrator architecture |\n| **2.0.5** | 2025-10-02 | Workspace switching system |\n| **2.0.0** | 2025-09-23 | Configuration system migration |\n\n---\n\n**Maintained By**: Provisioning Team\n**Last Review**: 2025-10-06\n**Next Review**: 2026-01-06
