\n \n

\n

\n \n

\n\n---\n\n# Platform Services\n\nPlatform-level services for the [Provisioning project](https://repo.jesusperez.pro/jesus/provisioning) infrastructure automation platform.\nThese services provide the high-performance execution layer, management interfaces, and supporting infrastructure for the entire provisioning system.\n\n## Overview\n\nThe Platform layer consists of **production-ready services** built primarily in Rust, providing:\n\n- **Workflow Execution** - High-performance orchestration and task coordination\n- **Management Interfaces** - Web UI and REST APIs for infrastructure management\n- **Security & Authorization** - Enterprise-grade access control and permissions\n- **Installation & Distribution** - Multi-mode installer with TUI, CLI, and unattended modes\n- **AI Integration** - Model Context Protocol (MCP) server for intelligent assistance\n- **Extension Management** - OCI-based registry for distributing modules\n\n---\n\n## Core Platform Services\n\n### 1. **Orchestrator** (`orchestrator/`)\n\nHigh-performance Rust/Nushell hybrid orchestrator for workflow execution.\n\n**Language**: Rust + Nushell integration\n\n**Purpose**: Workflow execution, task scheduling, state management\n\n**Key Features**:\n\n- File-based persistence for reliability\n- Priority processing with retry logic\n- Checkpoint recovery and automatic rollback\n- REST API endpoints for external integration\n- Solves deep call stack limitations\n- Parallel task execution with dependency resolution\n\n**Status**: ✅ Production Ready (v3.0.0)\n\n**Documentation**: See [.claude/features/orchestrator-architecture.md](../../.claude/features/orchestrator-architecture.md)\n\n**Quick Start**:\n\n```\ncd orchestrator\n./scripts/start-orchestrator.nu --background\n```\n\n**REST API**:\n\n- `GET http://localhost:8080/health` - Health check\n- `GET http://localhost:8080/tasks` - List all tasks\n- `POST http://localhost:8080/workflows/servers/create` - Server workflow\n- `POST http://localhost:8080/workflows/taskserv/create` - Taskserv workflow\n\n---\n\n### 2. **Control Center** (`control-center/`)\n\nBackend control center service with authorization and permissions management.\n\n**Language**: Rust\n\n**Purpose**: Web-based infrastructure management with RBAC\n\n**Key Features**:\n\n- **Authorization and permissions control** (enterprise security)\n- Role-Based Access Control (RBAC)\n- Audit logging and compliance tracking\n- System management APIs\n- Configuration management\n- Resource monitoring\n\n**Status**: ✅ Active Development\n\n**Security Features**:\n\n- Fine-grained permissions system\n- User authentication and session management\n- API key management\n- Activity audit logs\n\n---\n\n### 3. **Control Center UI** (`control-center-ui/`)\n\nFrontend web interface for infrastructure management.\n\n**Language**: Web (HTML/CSS/JavaScript)\n\n**Purpose**: User-friendly dashboard and administration interface\n\n**Key Features**:\n\n- Dashboard with real-time monitoring\n- Configuration management interface\n- System administration tools\n- Workflow visualization\n- Log viewing and search\n\n**Status**: ✅ Active Development\n\n**Integration**: Communicates with Control Center backend and Orchestrator APIs\n\n---\n\n### 4. **Installer** (`installer/`)\n\nMulti-mode platform installation system with interactive TUI, headless CLI, and unattended modes.\n\n**Language**: Rust (Ratatui TUI) + Nushell scripts\n\n**Purpose**: Platform installation and configuration generation\n\n**Key Features**:\n\n- **Interactive TUI Mode**: Beautiful terminal UI with 7 screens\n- **Headless Mode**: CLI automation for scripted installations\n- **Unattended Mode**: Zero-interaction CI/CD deployments\n- **Deployment Modes**: Solo (2 CPU/4GB), MultiUser (4 CPU/8GB), CICD (8 CPU/16GB), Enterprise (16 CPU/32GB)\n- **MCP Integration**: 7 AI-powered settings tools for intelligent configuration\n- **Nushell Scripts**: Complete deployment automation for Docker, Podman, Kubernetes, OrbStack\n\n**Status**: ✅ Production Ready (v3.5.0)\n\n**Quick Start**:\n\n```\n# Interactive TUI\nprovisioning-installer\n\n# Headless mode\nprovisioning-installer --headless --mode solo --yes\n\n# Unattended CI/CD\nprovisioning-installer --unattended --config config.toml\n```\n\n**Documentation**: `installer/docs/` - Complete guides and references\n\n---\n\n### 5. **MCP Server** (`mcp-server/`)\n\nModel Context Protocol server for AI-powered assistance.\n\n**Language**: Nushell\n\n**Purpose**: AI integration for intelligent configuration and assistance\n\n**Key Features**:\n\n- 7 AI-powered settings tools\n- Intelligent config completion\n- Natural language infrastructure queries\n- Configuration validation and suggestions\n- Context-aware help system\n\n**Status**: ✅ Active Development\n\n**MCP Tools**:\n\n- Settings generation\n- Configuration validation\n- Best practice recommendations\n- Infrastructure planning assistance\n- Error diagnosis and resolution\n\n---\n\n### 6. **OCI Registry** (`infrastructure/oci-registry/`)\n\nOCI-compliant registry for extension distribution and versioning.\n\n**Purpose**: Distributing and managing extensions\n\n**Key Features**:\n\n- Task service packages\n- Provider packages\n- Cluster templates\n- Workflow definitions\n- Version management and updates\n- Dependency resolution\n\n**Status**: 🔄 Planned\n\n**Benefits**:\n\n- Centralized extension management\n- Version control and rollback\n- Dependency tracking\n- Community marketplace ready\n\n---\n\n### 7. **API Gateway** (`infrastructure/api-gateway/`)\n\nUnified REST API gateway for external integration.\n\n**Language**: Rust\n\n**Purpose**: API routing, authentication, and rate limiting\n\n**Key Features**:\n\n- Request routing to backend services\n- Authentication and authorization\n- Rate limiting and throttling\n- API versioning\n- Request validation\n- Metrics and monitoring\n\n**Status**: 🔄 Planned\n\n**Endpoints** (Planned):\n\n- `/api/v1/servers/*` - Server management\n- `/api/v1/taskservs/*` - Task service operations\n- `/api/v1/clusters/*` - Cluster operations\n- `/api/v1/workflows/*` - Workflow management\n\n---\n\n### 8. **Extension Registry** (`extension-registry/`)\n\nRegistry and catalog for browsing and discovering extensions.\n\n**Purpose**: Extension discovery and metadata management\n\n**Key Features**:\n\n- Extension catalog\n- Search and filtering\n- Version history\n- Dependency information\n- Documentation links\n- Community ratings (future)\n\n**Status**: 🔄 Planned\n\n---\n\n### 9. **Provisioning Server** (`provisioning-server/`)\n\nAlternative provisioning service implementation.\n\n**Purpose**: Additional provisioning service capabilities\n\n**Status**: 🔄 In Development\n\n---\n\n## Supporting Services\n\n### CoreDNS (`config/coredns/`)\n\nDNS service configuration for cluster environments.\n\n**Purpose**: Service discovery and DNS resolution\n\n**Status**: ✅ Configuration Ready\n\n---\n\n### Monitoring (`infrastructure/monitoring/`)\n\nObservability and monitoring infrastructure.\n\n**Purpose**: Metrics, logging, and alerting\n\n**Components**:\n\n- Prometheus configuration\n- Grafana dashboards\n- Alert rules\n\n**Status**: ✅ Configuration Ready\n\n---\n\n### Nginx (`infrastructure/nginx/`)\n\nReverse proxy and load balancer configurations.\n\n**Purpose**: HTTP routing and SSL termination\n\n**Status**: ✅ Configuration Ready\n\n---\n\n### Docker Compose (`infrastructure/docker/`)\n\nDocker Compose configurations for local development.\n\n**Purpose**: Quick local platform deployment\n\n**Status**: ✅ Ready for Development\n\n---\n\n### Systemd (`infrastructure/systemd/`)\n\nSystemd service units for platform services.\n\n**Purpose**: Production deployment with systemd\n\n**Status**: ✅ Ready for Production\n\n---\n\n## Architecture\n\n```\n┌─────────────────────────────────────────────────\n────────────┐\n│ User Interfaces │\n│ • CLI (provisioning command) │\n│ • Web UI (Control Center UI) │\n│ • API Clients │\n└─────────────────────────────────────────────────\n────────────┘\n ↓\n┌─────────────────────────────────────────────────\n────────────┐\n│ API Gateway │\n│ • Request Routing │\n│ • Authentication & Authorization │\n│ • Rate Limiting │\n└─────────────────────────────────────────────────\n────────────┘\n ↓\n┌─────────────────────────────────────────────────\n────────────┐\n│ Platform Services Layer │\n│ │\n│ ┌──────────────┐ ┌──────────────┐ \n┌──────────────┐ │\n│ │ Orchestrator │ │Control Center│ │ MCP Server │ │\n│ │ (Rust) │ │ (Rust) │ │ (Nushell) │ │\n│ └──────────────┘ └──────────────┘ \n└──────────────┘ │\n│ │\n│ ┌──────────────┐ ┌──────────────┐ \n┌──────────────┐ │\n│ │ Installer │ │ OCI Registry │ │ Extension │ │\n│ │(Rust/Nushell)│ │ │ │ Registry │ │\n│ └──────────────┘ └──────────────┘ \n└──────────────┘ │\n└─────────────────────────────────────────────────\n────────────┘\n ↓\n┌─────────────────────────────────────────────────\n────────────┐\n│ Data & State Layer │\n│ • SurrealDB (State Management) │\n│ • File-based Persistence (Checkpoints) │\n│ • Configuration Storage │\n└─────────────────────────────────────────────────\n────────────┘\n```\n\n---\n\n## Technology Stack\n\n### Primary Languages\n\n| Language | Usage | Services |\n| ---------- | ------- | ---------- |\n| **Rust** | Platform services, performance layer | Orchestrator, Control Center, Installer, API Gateway |\n| **Nushell** | Scripting, automation, MCP integration | MCP Server, Installer scripts |\n| **Web** | Frontend interfaces | Control Center UI |\n\n### Key Dependencies\n\n- **tokio** - Async runtime for Rust services\n- **axum** / **actix-web** - Web frameworks\n- **serde** - Serialization/deserialization\n- **bollard** - Docker API client (test environments)\n- **ratatui** - Terminal UI framework (installer)\n- **SurrealDB** - State management database\n\n---\n\n## Deployment Modes\n\n### 1. **Development Mode**\n\n```\n# Docker Compose for local development\ndocker-compose -f infrastructure/docker/dev.yml up\n```\n\n### 2. **Production Mode (Systemd)**\n\n```\n# Install systemd units\nsudo cp infrastructure/systemd/*.service /etc/infrastructure/systemd/system/\nsudo systemctl daemon-reload\nsudo systemctl enable --now provisioning-orchestrator\nsudo systemctl enable --now provisioning-control-center\n```\n\n### 3. **Kubernetes Deployment**\n\n```\n# Deploy platform services to Kubernetes\nkubectl apply -f k8s/\n```\n\n---\n\n## Security Features\n\n### Enterprise Security Stack\n\n1. **Authorization & Permissions** (Control Center)\n - Role-Based Access Control (RBAC)\n - Fine-grained permissions\n - Audit logging\n\n2. **Authentication**\n - API key management\n - Session management\n - Token-based auth (JWT)\n\n3. **Secrets Management**\n - Integration with SOPS/Age\n - Cosmian KMS support\n - Secure configuration storage\n\n4. **Policy Enforcement**\n - Cedar policy engine integration\n - Compliance checking\n - Anomaly detection\n\n---\n\n## Getting Started\n\n### Prerequisites\n\n- **Rust** - Latest stable (for building platform services)\n- **Nushell 0.107.1+** - For MCP server and scripts\n- **Docker** (optional) - For containerized deployment\n- **Kubernetes** (optional) - For K8s deployment\n\n### Building Platform Services\n\n```\n# Build all Rust services\ncd orchestrator && cargo build --release\ncd ../control-center && cargo build --release\ncd ../installer && cargo build --release\n```\n\n### Running Services\n\n```\n# Start orchestrator\ncd orchestrator\n./scripts/start-orchestrator.nu --background\n\n# Start control center\ncd control-center\ncargo run --release\n\n# Start MCP server\ncd mcp-server\nnu run.nu\n```\n\n---\n\n## Development\n\n### Project Structure\n\n```\nplatform/\n├── orchestrator/ # Rust orchestrator service\n├── control-center/ # Rust control center backend\n├── control-center-ui/ # Web frontend\n├── installer/ # Rust/Nushell installer\n├── mcp-server/ # Nushell MCP server\n├── infrastructure/api-gateway/ # Rust API gateway (planned)\n├── infrastructure/oci-registry/ # OCI registry (planned)\n├── extension-registry/ # Extension catalog (planned)\n├── provisioning-server/# Alternative service\n├── infrastructure/docker/ # Docker Compose configs\n├── k8s/ # Kubernetes manifests\n├── infrastructure/systemd/ # Systemd units\n└── docs/ # Platform documentation\n```\n\n### Adding New Services\n\n1. Create service directory in `platform/`\n2. Add README.md with service description\n3. Implement service following architecture patterns\n4. Add tests and documentation\n5. Update platform/README.md (this file)\n6. Add deployment configurations (docker-compose, k8s, systemd)\n\n---\n\n## Integration with [Provisioning](../../PROVISIONING.md)\n\nPlatform services integrate seamlessly with the [Provisioning](../../PROVISIONING.md) system:\n\n- **Core Engine** (`../core/`) provides CLI and libraries\n- **Extensions** (`../extensions/`) provide providers, taskservs, clusters\n- **Platform Services** (this directory) provide execution and management\n- **Configuration** (`../kcl/`, `../config/`) defines infrastructure\n\n---\n\n## Documentation\n\n### Platform Documentation\n\n- **Orchestrator**: [.claude/features/orchestrator-architecture.md](../../.claude/features/orchestrator-architecture.md)\n- **Installer**: `installer/docs/` directory\n- **Test Environments**: [.claude/features/test-environment-service.md](../../.claude/features/test-environment-service.md)\n\n### API Documentation\n\n- **REST API Reference**: `docs/api/` (when orchestrator is running)\n- **MCP Tools Reference**: `mcp-server/docs/`\n\n### Architecture Documentation\n\n- **Main Project**: [PROVISIONING.md](../../PROVISIONING.md)\n- **Project Architecture**: [CLAUDE.md](../../CLAUDE.md)\n\n---\n\n## Contributing\n\nWhen contributing to platform services:\n\n1. **Follow Rust Best Practices** - Idiomatic Rust, proper error handling\n2. **Security First** - Always consider security implications\n3. **Performance Matters** - Platform services are performance-critical\n4. **Document APIs** - All REST endpoints must be documented\n5. **Add Tests** - Unit tests and integration tests required\n6. **Update Docs** - Keep README and API docs current\n\n---\n\n## Status Legend\n\n- ✅ **Production Ready** - Fully implemented and tested\n- ✅ **Active Development** - Working implementation, ongoing improvements\n- ✅ **Configuration Ready** - Configuration files ready for deployment\n- 🔄 **Planned** - Design phase, implementation pending\n- 🔄 **In Development** - Early implementation stage\n\n---\n\n## Support\n\nFor platform service issues:\n\n- Check service-specific README in service directory\n- Review logs: `journalctl -u provisioning-*` (systemd)\n- API documentation: `http://localhost:8080/docs` (when running)\n- See [Provisioning project](https://repo.jesusperez.pro/jesus/provisioning) for general support\n\n---\n\n**Maintained By**: Platform Team\n**Last Updated**: 2025-10-07\n**Platform Version**: 3.5.0