# Parallel Execution

When a [run](https://bluebricks.co/docs/core-concepts/runs) starts, Bluebricks builds a dependency graph (DAG) from the Data references in your blueprint. Independent packages execute in parallel; dependent packages wait for their inputs to be ready.

## Data references

Data references let one package consume the outputs of another:

```
Data.<packageId>.<outputKey>
```

* `Data.` is the reserved prefix for cross-package references
* `<packageId>` is the unique ID of the source package
* `<outputKey>` is the name of the output

<details>

<summary><strong>Example</strong></summary>

```json
{
  "packages": [
    {
      "id": "vpc_module",
      "props": {
        "region": { "value": "Props.region" }
      }
    },
    {
      "id": "eks_cluster",
      "props": {
        "vpc_id": { "value": "Data.vpc_module.vpc_id" },
        "subnet_ids": { "value": "Data.vpc_module.private_subnet_ids" }
      }
    }
  ]
}
```

</details>

Here `eks_cluster` depends on `vpc_module`. Bluebricks executes `vpc_module` first, then passes its `vpc_id` and `private_subnet_ids` outputs to `eks_cluster`.

### Data references in expressions

You can combine Data references with other values using [expr](https://bluebricks.co/docs/core-concepts/packages/blueprints-overview/expr) expressions:

<details>

<summary><strong>Example</strong></summary>

```json
{
  "props": {
    "bucket_name": {
      "value": "'my-app-' + Data.vpc_module.vpc_id + '-logs'"
    },
    "enable_logging": {
      "value": "Props.create_bucket || Data.s3_module.bucket_exists"
    }
  }
}
```

</details>

Expressions are evaluated at runtime after dependencies complete.

## Execution order

Bluebricks determines execution order automatically from your Data references. Consider this blueprint:

<details>

<summary><strong>Example</strong></summary>

```json
{
  "packages": [
    {
      "id": "launch_template",
      "props": {
        "name": { "value": "Props.template_name" }
      }
    },
    {
      "id": "s3_bucket",
      "props": {
        "bucket_name": {
          "value": "'logs-' + Data.launch_template.launch_template_id"
        }
      }
    },
    {
      "id": "monitoring",
      "props": {
        "template_id": {
          "value": "Data.launch_template.launch_template_id"
        }
      }
    }
  ]
}
```

</details>

{% @mermaid/diagram content="flowchart TD
LT\["launch\_template"]
S3\["s3\_bucket"]
MON\["monitoring"]

```
LT --> S3
LT --> MON" %}
```

`launch_template` runs first because it has no dependencies. Once it completes, `s3_bucket` and `monitoring` run **in parallel** since both depend only on `launch_template`.

Data references can also chain across nested blueprints — Bluebricks resolves the full dependency chain automatically, regardless of nesting depth.

## Tips for faster runs

Fewer Data references between packages means more parallel execution. Where possible, use `Props` (set at deployment time) instead of `Data` (resolved at runtime) to keep packages independent.

<details>

<summary><strong>Sequential:</strong> each package depends on the previous one</summary>

```json
{
  "packages": [
    { "id": "A" },
    { "id": "B", "props": { "input": { "value": "Data.A.output" } } },
    { "id": "C", "props": { "input": { "value": "Data.B.output" } } }
  ]
}
```

</details>

<details>

<summary><strong>Parallel:</strong> packages use properties instead of cross-package Data references</summary>

```json
{
  "packages": [
    { "id": "A", "props": { "input": { "value": "Props.value" } } },
    { "id": "B", "props": { "input": { "value": "Props.value" } } },
    { "id": "C", "props": { "input": { "value": "Props.value" } } }
  ]
}
```

</details>

## Best practices

* Use `Props` for static configuration, `Data` for runtime values
* Never create circular dependencies (A depends on B, B depends on A)
* Reference only outputs that will definitely be available
* Use descriptive output keys so Data references are self-documenting
* Keep expressions readable; avoid deeply nested logic

## See also

* [Runs](https://bluebricks.co/docs/core-concepts/runs)
* [Inputs & Outputs](https://bluebricks.co/docs/core-concepts/packages/inputs-and-outputs)
* [Creating Blueprints](https://bluebricks.co/docs/core-concepts/packages/blueprints-overview/creating-blueprints)
* [Using expr](https://bluebricks.co/docs/core-concepts/packages/blueprints-overview/expr)