# Home - Provisioning Platform Documentation
Complete documentation for the Provisioning Platform - Infrastructure automation with Nushell, KCL, and Rust

## Keyboard shortcuts

Press `←` or `→` to navigate between chapters

Press `S` or `/` to search in the book

Press `?` to show this help

Press `Esc` to hide this help

# Provisioning Platform Documentation

Last Updated: 2025-01-02 (Phase 3.A Cleanup Complete) Status: ✅ Primary documentation source (145 files consolidated)

Welcome to the comprehensive documentation for the Provisioning Platform - a modern, cloud-native infrastructure automation system built with Nushell, KCL, and Rust.

> Note: Architecture Decision Records (ADRs) and high-level design documentation are in `docs/` directory. This location contains all user-facing, operational, and product documentation.

## Quick Navigation

### 🚀 Getting Started

Document | Description | Audience
--- | --- | ---
Installation Guide | Install and configure the system | New Users
Getting Started | First steps and basic concepts | New Users
Quick Reference | Command cheat sheet | All Users
From Scratch Guide | Complete deployment walkthrough | New Users

### 📚 User Guides

Document | Description
--- | ---
CLI Reference | Complete command reference
Workspace Management | Workspace creation and management
Workspace Switching | Switch between workspaces
Infrastructure Management | Server, taskserv, cluster operations
Service Management | Platform service lifecycle management
OCI Registry | OCI artifact management
Gitea Integration | Git workflow and collaboration
CoreDNS Guide | DNS management
Test Environments | Containerized testing
Extension Development | Create custom extensions

### 🏗️ Architecture

Document | Description
--- | ---
System Overview | High-level architecture
Multi-Repo Architecture | Repository structure and OCI distribution
Design Principles | Architectural philosophy
Integration Patterns | System integration patterns
Orchestrator Model | Hybrid orchestration architecture

### 📋 Architecture Decision Records (ADRs)

ADR | Title | Status
--- | --- | ---
ADR-001 | Project Structure Decision | Accepted
ADR-002 | Distribution Strategy | Accepted
ADR-003 | Workspace Isolation | Accepted
ADR-004 | Hybrid Architecture | Accepted
ADR-005 | Extension Framework | Accepted
ADR-006 | CLI Refactoring | Accepted

### 🔌 API Documentation

Document | Description
--- | ---
REST API | HTTP API endpoints
WebSocket API | Real-time event streams
Extensions API | Extension integration APIs
SDKs | Client libraries
Integration Examples | API usage examples

### 🛠️ Development

Document | Description
--- | ---
Development README | Developer overview
Implementation Guide | Implementation details
Provider Development | Create cloud providers
Taskserv Development | Create task services
Extension Framework | Extension system
Command Handlers | CLI command development

### 🐛 Troubleshooting

Document | Description
--- | ---
Troubleshooting Guide | Common issues and solutions

### 📖 How-To Guides

Document | Description
--- | ---
From Scratch | Complete deployment from zero
Update Infrastructure | Safe update procedures
Customize Infrastructure | Layer and template customization

### 🔐 Configuration

Document | Description
--- | ---
Workspace Config Architecture | Configuration architecture

### 📦 Quick References

Document | Description
--- | ---
Quickstart Cheatsheet | Command shortcuts
OCI Quick Reference | OCI operations

## Documentation Structure

    provisioning/docs/src/
    ├── README.md (this file)          # Documentation hub
    ├── getting-started/               # Getting started guides
    │   ├── installation-guide.md
    │   ├── getting-started.md
    │   └── quickstart-cheatsheet.md
    ├── architecture/                  # System architecture
    │   ├── adr/                       # Architecture Decision Records
    │   ├── design-principles.md
    │   ├── integration-patterns.md
    │   ├── system-overview.md
    │   └── ... (and 10+ more architecture docs)
    ├── infrastructure/                # Infrastructure guides
    │   ├── cli-reference.md
    │   ├── workspace-setup.md
    │   ├── workspace-switching-guide.md
    │   └── infrastructure-management.md
    ├── api-reference/                 # API documentation
    │   ├── rest-api.md
    │   ├── websocket.md
    │   ├── integration-examples.md
    │   └── sdks.md
    ├── development/                   # Developer guides
    │   ├── README.md
    │   ├── implementation-guide.md
    │   ├── quick-provider-guide.md
    │   ├── taskserv-developer-guide.md
    │   └── ... (15+ more developer docs)
    ├── guides/                        # How-to guides
    │   ├── from-scratch.md
    │   ├── update-infrastructure.md
    │   └── customize-infrastructure.md
    ├── operations/                    # Operations guides
    │   ├── service-management-guide.md
    │   ├── coredns-guide.md
    │   └── ... (more operations docs)
    ├── security/                      # Security docs
    ├── integration/                   # Integration guides
    ├── testing/                       # Testing docs
    ├── configuration/                 # Configuration docs
    ├── troubleshooting/               # Troubleshooting guides
    └── quick-reference/               # Quick references
    ```plaintext

    ---

    ## Key Concepts

    ### Infrastructure as Code (IaC)

    The provisioning platform uses **declarative configuration** to manage infrastructure. Instead of manually creating resources, you define what you want in Nickel configuration files, and the system makes it happen.

    ### Mode-Based Architecture

    The system supports four operational modes:

    - **Solo**: Single developer local development
    - **Multi-user**: Team collaboration with shared services
    - **CI/CD**: Automated pipeline execution
    - **Enterprise**: Production deployment with strict compliance

    ### Extension System

    Extensibility through:

    - **Providers**: Cloud platform integrations (AWS, UpCloud, Local)
    - **Task Services**: Infrastructure components (Kubernetes, databases, etc.)
    - **Clusters**: Complete deployment configurations

    ### OCI-Native Distribution

    Extensions and packages distributed as OCI artifacts, enabling:

    - Industry-standard packaging
    - Efficient caching and bandwidth
    - Version pinning and rollback
    - Air-gapped deployments

    ---

    ## Documentation by Role

    ### For New Users

    1. Start with **[Installation Guide](getting-started/installation-guide.md)**
    2. Read **[Getting Started](getting-started/getting-started.md)**
    3. Follow **[From Scratch Guide](guides/from-scratch.md)**
    4. Reference **[Quickstart Cheatsheet](guides/quickstart-cheatsheet.md)**

    ### For Developers

    1. Review **[System Overview](architecture/system-overview.md)**
    2. Study **[Design Principles](architecture/design-principles.md)**
    3. Read relevant **[ADRs](architecture/)**
    4. Follow **[Development Guide](development/README.md)**
    5. Reference **KCL Quick Reference**

    ### For Operators

    1. Understand **[Mode System](infrastructure/mode-system)**
    2. Learn **[Service Management](operations/service-management-guide.md)**
    3. Review **[Infrastructure Management](infrastructure/infrastructure-management.md)**
    4. Study **[OCI Registry](integration/oci-registry-guide.md)**

    ### For Architects

    1. Read **[System Overview](architecture/system-overview.md)**
    2. Study all **[ADRs](architecture/)**
    3. Review **[Integration Patterns](architecture/integration-patterns.md)**
    4. Understand **[Multi-Repo Architecture](architecture/multi-repo-architecture.md)**

    ---

    ## System Capabilities

    ### ✅ Infrastructure Automation

    - Multi-cloud support (AWS, UpCloud, Local)
    - Declarative configuration with KCL
    - Automated dependency resolution
    - Batch operations with rollback

    ### ✅ Workflow Orchestration

    - Hybrid Rust/Nushell orchestration
    - Checkpoint-based recovery
    - Parallel execution with limits
    - Real-time monitoring

    ### ✅ Test Environments

    - Containerized testing
    - Multi-node cluster simulation
    - Topology templates
    - Automated cleanup

    ### ✅ Mode-Based Operation

    - Solo: Local development
    - Multi-user: Team collaboration
    - CI/CD: Automated pipelines
    - Enterprise: Production deployment

    ### ✅ Extension Management

    - OCI-native distribution
    - Automatic dependency resolution
    - Version management
    - Local and remote sources

    ---

    ## Key Achievements

    ### 🚀 Batch Workflow System (v3.1.0)

    - Provider-agnostic batch operations
    - Mixed provider support (UpCloud + AWS + local)
    - Dependency resolution with soft/hard dependencies
    - Real-time monitoring and rollback

    ### 🏗️ Hybrid Orchestrator (v3.0.0)

    - Solves Nushell deep call stack limitations
    - Preserves all business logic
    - REST API for external integration
    - Checkpoint-based state management

    ### ⚙️ Configuration System (v2.0.0)

    - Migrated from ENV to config-driven
    - Hierarchical configuration loading
    - Variable interpolation
    - True IaC without hardcoded fallbacks

    ### 🎯 Modular CLI (v3.2.0)

    - 84% reduction in main file size
    - Domain-driven handlers
    - 80+ shortcuts
    - Bi-directional help system

    ### 🧪 Test Environment Service (v3.4.0)

    - Automated containerized testing
    - Multi-node cluster topologies
    - CI/CD integration ready
    - Template-based configurations

    ### 🔄 Workspace Switching (v2.0.5)

    - Centralized workspace management
    - Single-command workspace switching
    - Active workspace tracking
    - User preference system

    ---

    ## Technology Stack

    | Component | Technology | Purpose |
    |-----------|------------|---------|
    | **Core CLI** | Nushell 0.107.1 | Shell and scripting |
    | **Configuration** | KCL 0.11.2 | Type-safe IaC |
    | **Orchestrator** | Rust | High-performance coordination |
    | **Templates** | Jinja2 (nu_plugin_tera) | Code generation |
    | **Secrets** | SOPS 3.10.2 + Age 1.2.1 | Encryption |
    | **Distribution** | OCI (skopeo/crane/oras) | Artifact management |

    ---

    ## Support

    ### Getting Help

    - **Documentation**: You're reading it!
    - **Quick Reference**: Run `provisioning sc` or `provisioning guide quickstart`
    - **Help System**: Run `provisioning help` or `provisioning <command> help`
    - **Interactive Shell**: Run `provisioning nu` for Nushell REPL

    ### Reporting Issues

    - Check **[Troubleshooting Guide](infrastructure/troubleshooting-guide.md)**
    - Review **[FAQ](troubleshooting/troubleshooting-guide.md)**
    - Enable debug mode: `provisioning --debug <command>`
    - Check logs: `provisioning platform logs <service>`

    ---

    ## Contributing

    This project welcomes contributions! See **[Development Guide](development/README.md)** for:

    - Development setup
    - Code style guidelines
    - Testing requirements
    - Pull request process

    ---

    ## License

    [Add license information]

    ---

    ## Version History

    | Version | Date | Major Changes |
    |---------|------|---------------|
    | **3.5.0** | 2025-10-06 | Mode system, OCI registry, comprehensive documentation |
    | **3.4.0** | 2025-10-06 | Test environment service |
    | **3.3.0** | 2025-09-30 | Interactive guides system |
    | **3.2.0** | 2025-09-30 | Modular CLI refactoring |
    | **3.1.0** | 2025-09-25 | Batch workflow system |
    | **3.0.0** | 2025-09-25 | Hybrid orchestrator architecture |
    | **2.0.5** | 2025-10-02 | Workspace switching system |
    | **2.0.0** | 2025-09-23 | Configuration system migration |

    ---

    **Maintained By**: Provisioning Team
    **Last Review**: 2025-10-06
    **Next Review**: 2026-01-06