provisioning/docs/src/architecture/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>

# 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

<p align="center">
    <img src="../resources/diagrams/architecture/system-overview.svg"
         alt="System Architecture Overview with 12 Microservices" width="800"/>
</p>

- **[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

<p align="center">
    <img src="../resources/diagrams/architecture/microservices-communication.svg"
         alt="Microservices Communication Patterns REST Async Events" width="800"/>
</p>

### 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/`