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

# Environment tree

> The parent-child hierarchy of your environments. Visualizes lineage and drives diff target selection, merge direction, and backup restore scope.

Environments form a tree rooted at `master`. Each environment has exactly one parent (the source it was branched from) and can have any number of children. The tree visualization is the right starting point for planning merges — it shows lineage at a glance and tells you which environments are eligible targets for a given merge.

<img src="https://mintcdn.com/archie-e998dbf6/zOlE9kC39qGD3yqx/features/backend/environments/environments-tree-structure.png?fit=max&auto=format&n=zOlE9kC39qGD3yqx&q=85&s=851756e39b0a161c58dacd072c216586" alt="Environment tree structure and status lifecycle" width="1603" height="260" data-path="features/backend/environments/environments-tree-structure.png" />

## What each node shows

Each node in the tree displays the metadata recorded when the environment was created:

| Field           | What it shows                                                                    |
| --------------- | -------------------------------------------------------------------------------- |
| **Name**        | Environment identifier — `master`, `staging`, `feature-auth`.                    |
| **Status**      | Current lifecycle state — `active`, `branching`, `merging`, `error`, `archived`. |
| **Parent**      | The environment this branch was created from.                                    |
| **Branch mode** | `full` (schema + data) or `system` (schema only).                                |
| **Branched at** | Timestamp when the branch was created.                                           |
| **Children**    | Other environments branched from this one.                                       |

For the full status lifecycle, see [Overview → Status lifecycle](/features/backend/environments/overview#status-lifecycle).

## Tree shape

* The tree is rooted at **`master`** — every project starts there and `master` can never be deleted.
* Each environment has **exactly one parent**.
* Each environment can have **zero or more children**.
* Branching is the only way to add a node. Merging schema between environments doesn't change the tree shape.

## When the tree matters

The tree shape isn't decorative — it informs three operations:

| Operation                  | How the tree drives it                                                                                                                                                                                                                                         |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Merge target selection** | The [merge UI](/features/backend/environments/merge) lets you pick any source/target pair, but the most common pattern is "merge child → parent" or "merge parent → child". The tree makes those relationships visible.                                        |
| **Backup restore scope**   | A backup is restored into a target environment. The tree tells you which environments are still around and which have been deleted (deleted nodes can be re-created via [restore](/features/backend/environments/backups#restoring-to-a-deleted-environment)). |
| **Deletion ordering**      | An environment with active children can't be deleted. The tree shows you the children to delete or archive first. See [Deleting](/features/backend/environments/deleting).                                                                                     |

## Reading the tree via GraphQL

Two queries cover the surface:

### `environmentTree` — nested structure

Returns the full tree with children nested under parents. Easiest to render directly in a UI.

```graphql theme={null}
query EnvironmentTree($projectId: String!) {
  environmentTree(projectId: $projectId) {
    success
    tree {
      environment {
        id
        name
        status
        parentName
        branchMode
        branchedAt
      }
      children {
        environment {
          id
          name
          status
          parentName
          branchMode
          branchedAt
        }
        children {
          environment { id name status }
        }
      }
    }
  }
}
```

### `projectEnvironments` — flat list

Returns every environment as a flat array. Useful for syncing the list into your own UI or for programmatic operations that don't need nesting.

```graphql theme={null}
query GetProjectEnvironments($projectId: String!) {
  projectEnvironments(projectId: $projectId) {
    success
    environments {
      id
      name
      parentId
      parentName
      branchMode
      branchedAt
      status
      createdAt
      updatedAt
    }
  }
}
```

## FAQ

<AccordionGroup>
  <Accordion title="Can an environment have multiple parents?">
    No. Each environment has exactly one parent — the source it was branched from. The tree is strict (no merging of branches into a DAG). Schema changes propagate via [merge](/features/backend/environments/merge), which doesn't change the tree shape.
  </Accordion>

  <Accordion title="What happens to children if I delete the parent?">
    You can't. An environment with active children can't be deleted. Delete or archive every child first, then the parent. See [Deleting](/features/backend/environments/deleting).
  </Accordion>

  <Accordion title="If I branch B from A, then merge changes from C into B, what does the tree look like?">
    Unchanged. B's parent is still A — the tree records lineage at branch time, not merge history. To see merge activity, look at [History](/features/backend/environments/history).
  </Accordion>

  <Accordion title="Can I rename an environment?">
    Names are stable identifiers. Renaming would invalidate every URL, integration credential, and migration record that references the old name. To "rename", branch a fresh environment with the new name and merge changes into it.
  </Accordion>

  <Accordion title="Is the tree visible in the dashboard?">
    Yes — open the environment switcher and choose the tree view. The same data is available via the GraphQL queries above for programmatic use.
  </Accordion>
</AccordionGroup>