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

# Infrastructure as Code

Define and manage infrastructure using Nickel, the type-safe configuration
language that serves as Provisioning's source of truth.

## Overview

Provisioning's infrastructure definition system provides:

- **Type-safe configuration** via Nickel language with mandatory schema validation and contract enforcement
- **Complete provider support** for AWS, UpCloud, Hetzner, Kubernetes, on-premise, and custom platforms
- **50+ task services** for specialized infrastructure operations (databases, monitoring, logging, networking)
- **Pre-built clusters** for common patterns (web, OCI registry, cache, distributed computing)
- **Batch workflows** with DAG scheduling, parallel execution, and multi-cloud orchestration
- **Schema validation** with inheritance, merging, and contracts ensuring correctness
- **Configuration composition** with includes, profiles, and environment-specific overrides
- **Version management** with semantic versioning and deprecation paths

All infrastructure is defined in Nickel (never TOML) ensuring compile-time correctness and runtime safety.

## Infrastructure Configuration Guides

### Core Configuration

- **[Nickel Guide](./nickel-guide.md)** - Syntax, types, contracts, lazy
  evaluation, record merging, patterns, best practices for IaC

<p align="center">
    <img src="../resources/diagrams/infrastructure/nickel-validation-flow.svg"
         alt="Nickel Validation Flow Type Checking Contract Validation" width="700"/>
</p>

- **[Configuration System](./configuration-system.md)** - Hierarchical loading,
  environment variables, profiles, composition, inheritance, validation

<p align="center">
    <img src="../resources/diagrams/infrastructure/configuration-loading.svg"
         alt="Configuration Loading Hierarchy Priority CLI Env User Workspace System" width="600"/>
</p>

- **[Schemas Reference](./schemas-reference.md)** - Contracts, types,
  validation rules, inheritance, composition, custom schema development

### Resources and Operations

- **[Providers Guide](./providers.md)** - AWS, UpCloud, Hetzner, Kubernetes,
  on-premise, demo with capabilities, resources, examples

- **[Task Services Guide](./task-services.md)** - 50+ services: databases,
  monitoring, logging, networking, CI/CD, storage

- **[Clusters Guide](./clusters.md)** - Web cluster (3-tier), OCI registry,
  cache cluster, distributed computing, Kubernetes operators

- **[Batch Workflows](./batch-workflows.md)** - DAG-based scheduling, parallel
  execution, logic, error handling, multi-cloud, state management

<p align="center">
    <img src="../resources/diagrams/workflows/batch-workflow-dag.svg"
         alt="Batch Workflow DAG Execution Parallel Tasks Dependencies" width="750"/>
</p>

### Advanced Topics

- **[Multi-Tenancy Patterns](./multi-tenancy-patterns.md)** - Workspace
  isolation, data separation, billing, resource limits, SLAs

<p align="center">
    <img src="../resources/diagrams/infrastructure/workspace-hierarchy.svg"
         alt="Workspace Hierarchy Structure Config Infra Schemas Extensions" width="600"/>
</p>

- **[Version Management](./version-management.md)** - Semantic versioning,
  dependency resolution, compatibility, deprecation, upgrade workflows

- **[Performance Optimization](./performance-optimization.md)** - Configuration
  caching, lazy evaluation, parallel validation, incremental updates

## Nickel as Source of Truth

**Critical principle**: Nickel is the source of truth for ALL infrastructure definitions.

- ✅ **Nickel**: Type-safe, validated, enforced, source of truth
- ❌ **TOML**: Generated output only, never hand-edited
- ❌ **JSON/YAML**: Generated output only, never source definitions
- ❌ **KCL**: Deprecated, completely replaced by Nickel

This ensures:

1. **Compile-time validation** - Errors caught before deployment
2. **Schema enforcement** - All configurations conform to contracts
3. **Type safety** - No runtime configuration errors
4. **IDE support** - Type hints and autocompletion via schema
5. **Evolution** - Breaking changes detected and reported

## Configuration Hierarchy

Configurations load in order of precedence:

```text
1. Command-line arguments       (highest priority)
2. Environment variables        (PROVISIONING_*)
3. User configuration          (~/.config/provisioning/user.nickel)
4. Workspace configuration     (workspace/config/main.nickel)
5. Infrastructure schemas      (provisioning/schemas/)
6. System defaults            (provisioning/config/defaults.toml)
                               (lowest priority)
```

## Quick Start Paths

### I'm new to Nickel
Start with [Nickel Guide](./nickel-guide.md) - language syntax, type system, functions, patterns with infrastructure examples.

### I need to define infrastructure
Read [Configuration System](./configuration-system.md) - how configurations load, compose, and validate.

### I want to use AWS/UpCloud/Hetzner
See [Providers Guide](./providers.md) - capabilities, resources, configuration examples for each cloud.

### I need databases, monitoring, logging
Check [Task Services Guide](./task-services.md) - 50+ services with configuration examples.

### I want to deploy web applications
Review [Clusters Guide](./clusters.md) - pre-built 3-tier web cluster, load balancer, database, caching.

### I need multi-cloud workflows
Learn [Batch Workflows](./batch-workflows.md) - DAG scheduling across multiple providers.

### I need multi-tenant setup
Study [Multi-Tenancy Patterns](./multi-tenancy-patterns.md) - isolation, billing, resource management.

## Example Nickel Configuration

```nickel
{
  extensions = {
    providers = [
      {
        name = "aws",
        version = "1.2.3",
        enabled = true,
        config = {
          region = "us-east-1",
          credentials_source = "aws_iam"
        }
      }
    ]
  },

  infrastructure = {
    networks = [
      {
        name = "main",
        provider = "aws",
        cidr = "10.0.0.0/16",
        subnets = [
          { cidr = "10.0.1.0/24", availability_zone = "us-east-1a" },
          { cidr = "10.0.2.0/24", availability_zone = "us-east-1b" }
        ]
      }
    ],

    instances = [
      {
        name = "web-server-1",
        provider = "aws",
        instance_type = "t3.large",
        image = "ubuntu-22.04",
        network = "main",
        subnet = "10.0.1.0/24"
      }
    ]
  }
}
```

## Schema Contracts

All infrastructure must conform to schemas. Schemas define:

- **Required fields** - Must be provided
- **Type constraints** - Values must match type
- **Field contracts** - Custom validation logic
- **Defaults** - Applied automatically
- **Documentation** - Inline help and examples

## Validation and Testing

Before deploying:

1. **Schema validation** - `provisioning validate config`
2. **Syntax checking** - `provisioning validate syntax`
3. **Policy checks** - Custom policy validation
4. **Unit tests** - Test configuration logic
5. **Integration tests** - Dry-run with actual providers

## Related Documentation

- **Provisioning Schemas** → See `provisioning/schemas/` in codebase
- **Configuration Examples** → See `provisioning/docs/src/examples/`
- **Provider Examples** → See `provisioning/docs/src/examples/aws-deployment-examples.md`
- **Task Services** → See `provisioning/extensions/` in codebase
- **API Reference** → See `provisioning/docs/src/api-reference/`
