provisioning/docs/src/README.md

<p align="center">
  <img src="resources/provisioning_logo.svg" alt="Provisioning Logo" width="300"/>
</p>
<p align="center">
  <img src="resources/logo-text.svg" alt="Provisioning" width="500"/>
</p>

# Provisioning Platform Documentation

**Last Updated**: 2025-10-06

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

---

## Quick Navigation

### 🚀 Getting Started

| Document | Description | Audience |
|----------|-------------|----------|
| **[Installation Guide](user/installation-guide.md)** | Install and configure the system | New Users |
| **[Getting Started](user/getting-started.md)** | First steps and basic concepts | New Users |
| **[Quick Reference](guides/quickstart-cheatsheet.md)** | Command cheat sheet | All Users |
| **[From Scratch Guide](guides/from-scratch.md)** | Complete deployment walkthrough | New Users |

### 📚 User Guides

| Document | Description |
|----------|-------------|
| **[CLI Reference](user/cli-reference.md)** | Complete command reference |
| **[Workspace Management](user/workspace-setup.md)** | Workspace creation and management |
| **[Workspace Switching](user/WORKSPACE_SWITCHING_GUIDE.md)** | Switch between workspaces |
| **[Infrastructure Management](user/infrastructure-management.md)** | Server, taskserv, cluster operations |
| **[Mode System](user/MODE_SYSTEM_QUICK_REFERENCE.md)** | Solo, Multi-user, CI/CD, Enterprise modes |
| **[Service Management](user/SERVICE_MANAGEMENT_GUIDE.md)** | Platform service lifecycle management |
| **[OCI Registry](user/OCI_REGISTRY_GUIDE.md)** | OCI artifact management |
| **[Gitea Integration](user/GITEA_INTEGRATION_GUIDE.md)** | Git workflow and collaboration |
| **[CoreDNS Guide](user/COREDNS_GUIDE.md)** | DNS management |
| **[Test Environments](user/test-environment-usage.md)** | Containerized testing |
| **[Extension Development](user/extension-development.md)** | Create custom extensions |

### 🏗️ Architecture

| Document | Description |
|----------|-------------|
| **[System Overview](architecture/system-overview.md)** | High-level architecture |
| **[Multi-Repo Architecture](architecture/MULTI_REPO_ARCHITECTURE.md)** | Repository structure and OCI distribution |
| **[Design Principles](architecture/design-principles.md)** | Architectural philosophy |
| **[Integration Patterns](architecture/integration-patterns.md)** | System integration patterns |
| **[KCL Import Patterns](architecture/kcl-import-patterns.md)** | KCL module organization |
| **[Orchestrator Model](architecture/orchestrator-integration-model.md)** | Hybrid orchestration architecture |

### 📋 Architecture Decision Records (ADRs)

| ADR | Title | Status |
|-----|-------|--------|
| **[ADR-001](architecture/ADR-001-project-structure.md)** | Project Structure Decision | Accepted |
| **[ADR-002](architecture/ADR-002-distribution-strategy.md)** | Distribution Strategy | Accepted |
| **[ADR-003](architecture/ADR-003-workspace-isolation.md)** | Workspace Isolation | Accepted |
| **[ADR-004](architecture/ADR-004-hybrid-architecture.md)** | Hybrid Architecture | Accepted |
| **[ADR-005](architecture/ADR-005-extension-framework.md)** | Extension Framework | Accepted |
| **[ADR-006](architecture/ADR-006-provisioning-cli-refactoring.md)** | CLI Refactoring | Accepted |

### 🔌 API Documentation

| Document | Description |
|----------|-------------|
| **[REST API](api/rest-api.md)** | HTTP API endpoints |
| **[WebSocket API](api/websocket.md)** | Real-time event streams |
| **[Extensions API](api/extensions.md)** | Extension integration APIs |
| **[SDKs](api/sdks.md)** | Client libraries |
| **[Integration Examples](api/integration-examples.md)** | API usage examples |

### 🛠️ Development

| Document | Description |
|----------|-------------|
| **[Development README](development/README.md)** | Developer overview |
| **[Implementation Guide](development/implementation-guide.md)** | Implementation details |
| **[KCL Module System](development/kcl/KCL_MODULE_SYSTEM_IMPLEMENTATION.md)** | KCL organization |
| **[KCL Quick Reference](development/kcl/KCL_QUICK_REFERENCE.md)** | KCL syntax and patterns |
| **[Provider Development](development/QUICK_PROVIDER_GUIDE.md)** | Create cloud providers |
| **[Taskserv Development](development/TASKSERV_DEVELOPER_GUIDE.md)** | Create task services |
| **[Extension Framework](development/extensions.md)** | Extension system |
| **[Command Handlers](development/COMMAND_HANDLER_GUIDE.md)** | CLI command development |

### 🐛 Troubleshooting

| Document | Description |
|----------|-------------|
| **[Troubleshooting Guide](user/troubleshooting-guide.md)** | Common issues and solutions |
| **[CTRL-C Handling](troubleshooting/CTRL-C_SUDO_HANDLING.md)** | Signal and sudo handling |

### 📖 How-To Guides

| Document | Description |
|----------|-------------|
| **[From Scratch](guides/from-scratch.md)** | Complete deployment from zero |
| **[Update Infrastructure](guides/update-infrastructure.md)** | Safe update procedures |
| **[Customize Infrastructure](guides/customize-infrastructure.md)** | Layer and template customization |

### 🔐 Configuration

| Document | Description |
|----------|-------------|
| **[Configuration Guide](user/configuration.md)** | Configuration system overview |
| **[Workspace Config Architecture](configuration/workspace-config-architecture.md)** | Configuration architecture |
| **[Target-Based Config](configuration/TARGET_BASED_CONFIG_COMPLETE_IMPLEMENTATION.md)** | Configuration targeting |

### 📦 Quick References

| Document | Description |
|----------|-------------|
| **[Quickstart Cheatsheet](guides/quickstart-cheatsheet.md)** | Command shortcuts |
| **[OCI Quick Reference](QUICK_REFERENCE_OCI.md)** | OCI operations |
| **[Mode System Quick Reference](user/MODE_SYSTEM_QUICK_REFERENCE.md)** | Mode commands |
| **[CoreDNS Quick Reference](user/COREDNS_QUICK_REFERENCE.md)** | DNS commands |
| **[Service Management Quick Reference](user/SERVICE_MANAGEMENT_QUICKREF.md)** | Service commands |

---

## Documentation Structure

```
docs/
├── README.md (this file)          # Documentation hub
├── architecture/                  # System architecture
│   ├── ADR/                       # Architecture Decision Records
│   ├── design-principles.md
│   ├── integration-patterns.md
│   └── system-overview.md
├── user/                          # User guides
│   ├── getting-started.md
│   ├── cli-reference.md
│   ├── installation-guide.md
│   └── troubleshooting-guide.md
├── api/                           # API documentation
│   ├── rest-api.md
│   ├── websocket.md
│   └── extensions.md
├── development/                   # Developer guides
│   ├── README.md
│   ├── implementation-guide.md
│   └── kcl/                       # KCL documentation
├── guides/                        # How-to guides
│   ├── from-scratch.md
│   ├── update-infrastructure.md
│   └── customize-infrastructure.md
├── configuration/                 # Configuration docs
│   └── workspace-config-architecture.md
├── troubleshooting/               # Troubleshooting
│   └── CTRL-C_SUDO_HANDLING.md
└── quick-reference/               # Quick refs
    └── SUDO_PASSWORD_HANDLING.md
```

---

## 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 KCL 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](user/installation-guide.md)**
2. Read **[Getting Started](user/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](development/kcl/KCL_QUICK_REFERENCE.md)**

### For Operators

1. Understand **[Mode System](user/MODE_SYSTEM_QUICK_REFERENCE.md)**
2. Learn **[Service Management](user/SERVICE_MANAGEMENT_GUIDE.md)**
3. Review **[Infrastructure Management](user/infrastructure-management.md)**
4. Study **[OCI Registry](user/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](user/troubleshooting-guide.md)**
- Review **[FAQ](user/troubleshooting-guide.md#faq)**
- 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