jesus/provisioning
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
provisioning/docs/src/architecture/README.md
Jesús Pérez 27dbc5cd08
chore: review docs from scratch
2026-01-17 03:58:28 +00:00

4.1 KiB
Raw Blame History

Provisioning Logo

Provisioning

Architecture

Deep dive into Provisioning platform architecture, design principles, and architectural decisions that shape the system.

Overview

The Provisioning platform uses modular, microservice-based architecture for enterprise infrastructure as code across multiple clouds. This section documents foundational architectural decisions and system design that enable:

  • Multi-cloud orchestration across AWS, UpCloud, Hetzner, Kubernetes, and on-premise systems
  • Workspace-first organization with complete infrastructure isolation and multi-tenancy support
  • Type-safe configuration using Nickel language as source of truth
  • Autonomous operations through intelligent detectors and automated incident response
  • Post-quantum security with hybrid encryption protecting against future threats

Architecture Documentation

System Understanding

System Architecture Overview with 12 Microservices

  • System Overview - Platform architecture with 12 microservices, 80+ CLI commands, multi-tenancy model, cloud integration

  • Design Principles - Configuration-driven design, workspace isolation, type-safety mandates, autonomous operations, security-first

  • Component Architecture - 12 microservices: Orchestrator, Control-Center, Vault-Service, Extension-Registry, AI-Service, Detector, RAG, MCP-Server, KMS, Platform-Config, Service-Clients

  • Integration Patterns - REST APIs, async message queues, event-driven workflows, service discovery, state management

Microservices Communication Patterns REST Async Events

Architectural Decisions

  • Architecture Decision Records (ADRs) - 10 decisions: modular CLI, workspace-first design, Nickel type-safety, microservice distribution, communication, post-quantum cryptography, encryption, observability, SLO management, incident automation

Key Architectural Patterns

Modular Design (ADR-001)

  • Decentralized CLI command registration reducing code by 84%
  • Dynamic command discovery and 80+ keyboard shortcuts
  • Extensible architecture supporting custom commands

Workspace-First Organization (ADR-002)

  • Workspaces as primary organizational unit grouping infrastructure, configs, and state
  • Complete isolation for multi-tenancy and team collaboration
  • Local schema and extension customization per workspace

Type-Safe Configuration (ADR-003)

  • Nickel language as source of truth for all infrastructure definitions
  • Mandatory schema validation at parse time (not runtime)
  • Complete migration from KCL with backward compatibility

Distributed Microservices (ADR-004)

  • 12 specialized microservices handling specific domains
  • Independent scaling and deployment per service
  • Service communication via REST + async queues

Security Architecture (ADR-006 & ADR-007)

  • Post-quantum cryptography with CRYSTALS-Kyber hybrid encryption
  • Multi-layer encryption: at-rest (KMS), in-transit (TLS 1.3), field-level, end-to-end
  • Centralized secrets management via SecretumVault

Observability & Resilience (ADR-008, ADR-009, ADR-010)

  • Unified observability: Prometheus metrics, ELK logging, Jaeger tracing
  • SLO-driven operations with error budget enforcement
  • Autonomous incident detection and self-healing

Navigation

  • For implementation details → See provisioning/docs/src/features/
  • For API documentation → See provisioning/docs/src/api-reference/
  • For deployment guides → See provisioning/docs/src/operations/
  • For security details → See provisioning/docs/src/security/
  • For development → See provisioning/docs/src/development/