## 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, Nickel, and Rust.

> Note: Architecture Decision Records (ADRs) and design documentation are in `docs/` directory. This location contains 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

## 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
2. Read Getting Started
3. Follow From Scratch Guide
4. Reference Quickstart Cheatsheet

### For Developers

1. Review System Overview
2. Study Design Principles
3. Read relevant ADRs
4. Follow Development Guide
5. Reference Nickel Quick Reference

### For Operators

1. Understand Mode System
2. Learn Service Management
3. Review Infrastructure Management
4. Study OCI Registry

### For Architects

1. Read System Overview
2. Study all ADRs
3. Review Integration Patterns
4. Understand Multi-Repo Architecture

## System Capabilities

### ✅ Infrastructure Automation

- Multi-cloud support (AWS, UpCloud, Local)
- Declarative configuration with Nickel
- 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 | Nickel 1.0.0+ | 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
- Review FAQ
- Enable debug mode: `provisioning --debug <command>`
- Check logs: `provisioning platform logs <service>`

## Contributing

This project welcomes contributions! See Development Guide 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