Provisioning Pipeline

When a user clicks "Plan" or "Apply", the platform transforms the Spec's form configuration into Terraform variables through a five-stage pipeline. Each stage has a single responsibility: serialize, freeze, deserialize, map, execute.

Stage 1: Form → Database

The Spec form in Console (or alethia plan in the CLI) calls createSpec(), which inserts the configuration into normalized component tables:

Each table stores the shared schema. Provider-specific options live in provider_config JSONB columns — see Cloud Provider Abstraction.

Stage 2: Database → Config Snapshot

When a job is queued, buildConfigSnapshot() in app/server/actions/specs.ts queries all component tables in parallel and assembles a single JSON object. This object is stored in provision_jobs.config_snapshot.

The snapshot is a point-in-time freeze. Even if the user edits the Spec after queuing, the job executes the exact configuration that was planned.

config_snapshot = {
  ...spec fields,
  provider: "aws" | "gcp" | "azure",
  network: { provision_network, cidr_block, network_id, ... },
  cluster: { cluster_version, instance_types, node_min_size, ... },
  dns:     { enabled, zone_id, domain_name, provider_config, ... },
  databases: [...],
  caches:    [...],
  queues:    [...],
  topics:    [...],
  nosql_tables: [...],
  secrets:   [...],
  git_access_token: ""   // fetched at runtime, not stored
}

Stage 3: Config Snapshot → SpecConfig

The Runner worker claims the job and deserializes the JSON snapshot into a strongly-typed Go struct:

func snapshotToSpecConfig(snapshot map[string]any) (*types.SpecConfig, error) {
    data, _ := json.Marshal(snapshot)
    var sc types.SpecConfig
    json.Unmarshal(data, &sc)
    return &sc, nil
}

The SpecConfig struct in packages/core/types/spec_config.go mirrors the snapshot shape with typed fields: Network, Cluster, DNS, Databases[], Caches[], and so on.

Stage 4: SpecConfig → terraform.tfvars.json

Each cloud provider implements a ProviderTfvars() method that maps SpecConfig fields to provider-specific Terraform variable names:

The result is a map[string]interface{} written to terraform.tfvars.json via OverrideTfvarsFromMap().

No templating engine touches the .tf files. The Terraform templates at infra/templates/spec/{aws,gcp,azure}/ are plain HCL with variable declarations. Values are injected entirely through Terraform's native tfvars mechanism.

Stage 5: Terraform Execution

Plan Hash Validation

When a DEPLOY job references a prior PLAN job, the platform validates that the configuration hasn't changed between plan and apply. If the config_snapshot hash differs, the deploy fails with a hash mismatch error and the user must re-plan. This prevents applying a stale plan against a modified Spec.

Key Implementation Files