provisioning/docs/src/README.md

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