# 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 Overview](./system-overview.md)** - Platform architecture with 12 microservices, 80+ CLI commands, multi-tenancy model, cloud integration - **[Design Principles](./design-principles.md)** - Configuration-driven design, workspace isolation, type-safety mandates, autonomous operations, security-first - **[Component Architecture](./component-architecture.md)** - 12 microservices: Orchestrator, Control-Center, Vault-Service, Extension-Registry, AI-Service, Detector, RAG, MCP-Server, KMS, Platform-Config, Service-Clients - **[Integration Patterns](./integration-patterns.md)** - REST APIs, async message queues, event-driven workflows, service discovery, state management

### Architectural Decisions - **[Architecture Decision Records (ADRs)](./adr/README.md)** - 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/`