# ADR-004: 12-Microservice Architecture for Platform Services

**Status**: Accepted | **Date**: 2025-01-16 | **Supersedes**: None

## Context

Provisioning platform requires distributed architecture to handle multi-cloud orchestration, security, extensibility, and scalability independently.

## Decision

The platform consists of 12 distinct Rust microservices, each with a single responsibility and independent deployment lifecycle.

## Rationale

**Scalability**: Each service scales independently based on load (orchestrator handles workflows, vault-service handles secrets)

**Resilience**: Service failure doesn't cascade (e.g., vault-service unavailability doesn't block orchestrator operation)

**Development**: Teams work on services independently without coordination on core logic

**Deployment**: Services update independently, enabling rapid iteration and rollback

## Architecture

### Core Services (5)

1. **Orchestrator** - Workflow execution, DAG scheduling, task coordination
   - Persistence: File-based (SurrealDB optional for clustering)
   - Responsibility: Batch workflows, blue-green deployments, rollback

2. **Control-Center** - Workspace management, configuration, settings
   - Persistence: SurrealDB (relationships)
   - Responsibility: Workspace CRUD, infrastructure state, user settings

3. **Control-Center-UI** - Web UI for infrastructure management
   - Framework: Rust Actix-web + frontend (WASM/React)
   - Responsibility: Dashboard, infrastructure visualization, settings UI

4. **Vault-Service** - Secrets management, encryption, key rotation
   - Integration: SecretumVault (post-quantum cryptography)
   - Responsibility: Secret CRUD, encryption at-rest, audit logging

5. **KMS (Key Management Service)** - Cryptographic key operations
   - Algorithms: AES-256, RSA-4096, CRYSTALS-Kyber, Falcon, SPHINCS+
   - Responsibility: Key generation, rotation, derivation, policy enforcement

### Support Services (4)

6. **Extension-Registry** - Marketplace for providers and plugins
   - Responsibility: Version management, discovery, installation, update checks

7. **AI-Service** - Infrastructure intelligence via LLMs and RAG
   - Backends: OpenAI, Anthropic, Ollama (local)
   - Responsibility: NLI processing, policy generation, infrastructure recommendations

8. **Detector** - Automatic infrastructure analysis and cost optimization
   - Responsibility: Resource rightsizing, cost anomalies, compliance violations

9. **RAG (Retrieval-Augmented Generation)** - Knowledge base and semantic search
   - Storage: SurrealDB vector embeddings (HNSW)
   - Responsibility: Document indexing, semantic search, relevance ranking

### Internal Services (3)

10. **MCP-Server (Model Context Protocol)** - LLM integration layer
    - Responsibility: Tool discovery, protocol translation, context management

11. **Platform-Config** - Distributed configuration management
    - Responsibility: Config distribution, secrets injection, environment-specific overrides

12. **Provisioning-Daemon** - Agent for on-premise/hybrid deployments
    - Responsibility: Local execution, reporting, health checks

### Service Communication

```text
CLI → Control-Center (workspace API)
   → Orchestrator (workflow execution)
   → Vault-Service (secrets)
   → Extension-Registry (plugin lookup)
   → AI-Service (intelligence)

Control-Center → SurrealDB (state)
              → MCP-Server (LLM tools)
              → RAG (knowledge)

Orchestrator → Provisioning-Daemon (execution)
            → Detector (analysis)
```

## Deployment Model

**Standard**: All 12 services deployed together
**Lightweight**: Core 5 services only (minimal footprint)
**Distributed**: Services split across availability zones
**On-Premise**: Orchestrator + Vault-Service + Daemon (no cloud dependencies)

## Consequences

- **Positive**:
  - Independent scaling and updates
  - Clear ownership (each service has team)
  - Parallel development (services don't block each other)
  - Technology choices per service (not all must be Rust)
  - Easy testing (mock services for unit tests)

- **Negative**:
  - Operational complexity (12 services to monitor)
  - Network latency between services
  - Distributed debugging challenges
  - Data consistency across services
  - Deployment coordination overhead

## Mitigation

1. **Monitoring**: Unified observability stack (Prometheus + Jaeger)
2. **Communication**: Synchronous REST (latency < 100ms), async queues for high-latency ops
3. **State Management**: SurrealDB as source of truth, services maintain caches
4. **Resilience**: Circuit breakers, timeouts, fallbacks, retries with exponential backoff
5. **Testing**: Integration test suite covering all service interactions

## Related ADRs

- [ADR-002: Workspace-First Design](./adr-002-workspace-first.md) - Services organized by workspace
- [ADR-005: Service Communication Protocol](./adr-005-service-communication.md) - REST/async patterns
