> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ubiquex.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Code Hierarchy — Root and Children

> Share backend, provider, and tag config across multiple stacks with ubx.root.iac.

A platform engineering team manages dozens of stacks across multiple services. Every stack needs the same S3 backend. Every stack should tag resources with `team` and `repo`. Every stack should use at least AWS provider v6. Without a hierarchy mechanism, you duplicate these declarations in every stack's `ubx.iac` file — and when the backend bucket name changes, you update it in every file. `ubx.root.iac` solves this: place it at the repository root and ubx automatically discovers it when validating or applying any child project in the directory tree below it. Backend config, provider version constraints, and shared tags cascade down to every child stack. Children inherit everything from root and can override any attribute locally — root wins only on attributes the child doesn't declare.

## What you'll learn

* How `ubx.root.iac` provides shared config inherited by all child stacks
* The merge rules: child wins on overlap, root fills in what child doesn't declare
* How `ubx validate --all` validates the entire hierarchy at once

***

## Why this matters

<Info>
  Code hierarchy is the difference between a platform with consistent defaults and a platform where every team independently decides their backend bucket name. `ubx.root.iac` is a single source of truth for org-wide infrastructure conventions — backend, provider versions, mandatory tags — that every stack inherits automatically.
</Info>

***

## The source code

<CodeGroup>
  ```hcl services/api/main.iac theme={"theme":"css-variables"}
  # No backend block — inherited from ubx.root.iac.
  # No default_tags — team and repo tags from ubx.root.iac are applied automatically.
  unit "aws_s3_bucket_v2" "api_assets" {
    bucket = "myapp-api-${input.env}-assets"
  }

  unit "aws_sqs_queue" "api_jobs" {
    name = "myapp-api-${input.env}-jobs"
  }
  ```

  ```hcl services/worker/main.iac theme={"theme":"css-variables"}
  # No backend block — inherited from ubx.root.iac.
  unit "aws_sqs_queue" "worker_jobs" {
    name                       = "myapp-worker-${input.env}-jobs"
    visibility_timeout_seconds = 300
  }

  unit "aws_lambda_function" "processor" {
    name      = "myapp-worker-${input.env}-processor"
    runtime   = "nodejs20.x"
    handler   = "index.handler"
    role      = "arn:aws:iam::123456789012:role/lambda-role"
    s3_bucket = "myapp-deployment-artifacts"
    s3_key    = "function.zip"
  }
  ```

  ```hcl ubx.root.iac theme={"theme":"css-variables"}
  # ubx.root.iac — shared config inherited by all child projects below this directory.
  # Provider blocks here are merged with child provider blocks; child wins on conflict.
  provider "aws" {
    version = ">= 6.0.0"
  }

  ubx {
    tags {
      team = "platform"
      repo = "ubx-examples"
    }
  }
  ```

  ```hcl services/api/ubx.iac theme={"theme":"css-variables"}
  ubx {
    name    = "api-service"
    runtime = "typescript"
    stacks  = ["dev", "staging", "prod"]
  }

  backend "s3" {
    bucket = "my-ubx-state"
    region = "us-east-1"
    key    = "api/${stack}/pulumi.json"
  }
  ```

  ```hcl services/worker/ubx.iac theme={"theme":"css-variables"}
  ubx {
    name    = "worker-service"
    runtime = "typescript"
    stacks  = ["dev", "staging", "prod"]
  }

  backend "s3" {
    bucket = "my-ubx-state"
    region = "us-east-1"
    key    = "worker/${stack}/pulumi.json"
  }
  ```
</CodeGroup>

***

## How it works

<Steps>
  <Step title="ubx walks up from the child directory to find ubx.root.iac">
    When you run `ubx validate` from `services/api/`, ubx walks up the directory tree looking for `ubx.root.iac`. It finds it two levels up at the repository root. The root discovery happens before compilation — the root config is merged into the child's compile context.
  </Step>

  <Step title="Root and child configs are merged">
    The merger applies root config as defaults. Child config overrides root on any attribute that appears in both. Tags are deep-merged: `team = "platform"` from root plus any child-declared tags coexist. Provider version constraints: child wins if it declares the same provider; root fills in providers the child doesn't declare.
  </Step>

  <Step title="ubx validate --all discovers and validates all children">
    From the repository root, `ubx validate --all` scans for all directories containing a `ubx.iac` file, applies the root config to each, and validates them all. `2 passed · 0 failed` means every child stack in the hierarchy is valid. This is the CI command for a monorepo.
  </Step>
</Steps>

***

## Merge rules

| Config type        | Merge behaviour                                                                                |
| ------------------ | ---------------------------------------------------------------------------------------------- |
| `tags {}`          | Deep merge — child tags and root tags coexist; child wins on overlapping keys                  |
| `provider` version | Child wins if same provider is declared in both; root fills in providers child doesn't declare |
| `backend`          | Child's backend block takes precedence; root backend is ignored if child declares one          |
| `runtime`          | Child's `ubx.iac` runtime wins; root can't override child runtime                              |

***

## Common mistakes

<Warning>
  `ubx.root.iac` is discovered by walking up from the child directory — it must be an ancestor of the child, not a sibling. If you place `ubx.root.iac` in `services/` rather than at the repo root, only stacks directly inside `services/` will discover it; stacks in `services/api/` will not.
</Warning>

<Tip>
  Run `ubx validate --all` from the repo root in CI rather than validating each stack separately. It applies root config to every child and validates the full hierarchy in one command — catching root config errors and child compatibility issues simultaneously.
</Tip>

***

## Run it

```bash theme={"theme":"css-variables"}
# From repo root:
ubx validate --all                    # validates all child stacks with root config

# From a child directory:
cd services/api
ubx validate                          # validates api stack, inherits root config
ubx plan                              # requires AWS credentials
```

***

## What you learned

<Check>`ubx.root.iac` at the repo root provides shared config inherited by all child stacks below it</Check>
<Check>Child config wins on overlap; root fills in attributes the child doesn't declare</Check>
<Check>`ubx validate --all` from the root validates every child stack in the hierarchy at once</Check>

***

## Next steps

<CardGroup cols={2}>
  <Card title="Multi-runtime compilation" href="/v1/tutorials/42-runtime-typescript">
    Compile the same .iac source to TypeScript, Python, or Go
  </Card>

  <Card title="ubx block reference" href="/v1/language/ubx-block">
    Full ubx block syntax and all configuration options
  </Card>
</CardGroup>

***

<Info>
  Full runnable example: [github.com/ubiquex/ubx-examples/41-code-hierarchy-root-and-children](https://github.com/ubiquex/ubx-examples/tree/main/41-code-hierarchy-root-and-children)
</Info>