---
title: "Resource model"
url: "https://docs.alisx.com/reference/environments/resource-model/"
---
# Resource model

The resources that make up Build, their names, fields and states. Names follow the `collection/id` pattern; the id patterns below are regular expressions.

```mermaid
flowchart TB
  O["Organisation<br/><small>build environment</small>"] --> P[Product]
  P --> E[Environment]
  P --> N["Neuron<br/><small>service</small>"]
  N --> V[NeuronVersion]
  E --> D[Deployment]
  V -. deployed as .-> D
  D --> DV[DeploymentVersion]
```

## Names

| Resource | Name format | Notes |
|---|---|---|
| Organisation | `organisations/([a-z0-9-]{2,20})` | Shown as a build environment in the console and the `alis org` command; historically a landing zone. |
| Product | `organisations/*/products/([a-z0-9-]{2})` | Two-character id. |
| Deployment environment | `organisations/*/products/*/environments/([a-z0-9-]{2,20})` | |
| Neuron (service) | `organisations/*/products/*/neurons/([a-z0-9-]{2,80})` | The id is the package path with `/` replaced by `-` plus the version, for example `orders-v1`. |
| NeuronVersion | `.../neurons/*/versions/([a-z0-9-]{2,50})` | The id is the version with dots replaced by hyphens, for example `1-0-1`. |
| Deployment | `.../environments/*/deployments/([a-z0-9-]{2,50})` | The id is always a neuron id, so a deployment environment has at most one deployment per service. |
| DeploymentVersion | `.../deployments/*/versions/*` | One per deploy of a deployment. |
| Package | `packages/<package-id>` | The contract package, for example `packages/acme.sh.orders.v1`. |

## Organisation

The top-level resource in which products are created. Each company normally has its own.

| Field | Meaning |
|---|---|
| `display_name`, `description`, `logo` | Presentation. |
| `google_project` | The Google Cloud project backing the organisation: `folder_id`, `id`, `number`, `region`, `billing_account_id`, `managed_billing_account`. |
| `buckets_domain` | Domain used for storage bucket names; `alis.build` by default. Injected as `ALIS_OS_DOMAIN`. |
| `packages_domain` | Domain for package namespaces; `{orgId}.exchange` by default. |
| `account` | The account paying for the organisation, `accounts/*`. Without one the organisation brings its own billing account and folder. |
| `spanner_instance` | The Spanner instance provisioned for the organisation, if any. |
| `service_account` | The IAM service account provisioned for the organisation. |
| `git_repo` | The definitions repository: `remote_uri` and its hosting. |
| `loadbalancer` | The organisation's load balancer. |
| `state` | `ACTIVE`, `FAILED`, `CREATING`, `UPDATING`, `DESTROYING`, `DELETING`. |
| `deploy_operation`, `last_successful_deploy_time`, `deploy_executions` | The organisation's own Terraform deploys; the last five executions are kept, each with an optional AI explanation of a failure. |

## Product

A self-standing product with a well-contained feature set, for example `sh` for a shop.

| Field | Meaning |
|---|---|
| `display_name`, `description`, `logo` | Presentation. `alis product rename` changes the display name only. |
| `google_project` | The product's Google Cloud project; hosts the image and package registries. |
| `spanner_database` | The managed Spanner database, auto-configured if left empty on creation. |
| `service_account` | The product's service account. |
| `git_repo` | The product's build repository. |
| `internal_package_registries` | Registry locations for the Go, JavaScript, Python, Dart, .NET, Swift and Rust packages generated by Define. |
| `docker_registries` | The product's container registry. |
| `state` | `ACTIVE`, `FAILED`, `CREATING`, `UPDATING`, `DESTROYING`, `DELETING`. |
| `deploy_operation`, `last_successful_deploy_time`, `deploy_executions` | The product's own Terraform deploys. |

A new product is provisioned with one development environment. A production environment is created explicitly.

## Deployment environment

A deployment target in a product, for example development, staging or production.

| Field | Meaning |
|---|---|
| `display_name`, `description` | Presentation. |
| `google_project` | The deployment environment's Google Cloud project, where deployments land. Injected as `ALIS_OS_PROJECT`, `ALIS_PROJECT_NR`, `ALIS_REGION`. |
| `type` | `DEV` or `PROD`. `PROD` deployment environments are gated on deploy and on variable changes. The Google Cloud project inherits an `environment` tag with the same value (`dev` or `prod`), which the Google Cloud console shows as a badge in its project picker. |
| `envs[]` | Environment variables: `name`, `value`, `store_in_secret_manager`. A secret-backed variable has no stored value and is left out of deployments. |
| `allowed_branches[]` | Branches designated for this deployment environment. When set, deploy flows warn before deploying a version built from another branch. Empty means any branch. |
| `monitoring_emails[]` | Addresses that receive alerts. |
| `state` | `ACTIVE`, `FAILED`, `CREATING`, `UPDATING`, `DESTROYING`, `DELETING`. |
| `deploy_operation`, `last_successful_deploy_time`, `deploy_executions` | The deployment environment's own Terraform deploys. |

## Neuron (service)

A product is made up of its neurons and their interactions; they split a product's features much like microservices. The console and CLI call them services.

| Field | Meaning |
|---|---|
| `package` | The contract package, `packages/<package-id>`. |
| `defined_version` | The latest successfully defined contract version. Patch zero is reserved for the contract, for example `1.56.0`. |
| `version`, `build_commit` | The latest build version and the build-repo commit it was built from. |
| `latest_version_state` | State of the latest version (see below). |
| `last_version_logs_uri` | Build logs of the latest version; empty when every image was retagged. |
| `last_version_created_by`, `last_version_create_time` | Who built the latest version and when. |
| `type` | `RELEASED` (available to other products) or `MANAGED` (builds and stubs come from another neuron). |
| `release_config` | For released neurons: the organisations that may install releases (empty means public) and the optional and required environment variables of a release. |
| `managed_config` | For managed neurons: the source neuron and the deployment environments to auto-deploy to on a new release. |
| `details.description` | An AI-generated description from the protos and build files. |

## NeuronVersion

An immutable version of a service, created by Build.

| Field | Meaning |
|---|---|
| `version` | Semantic version, for example `1.0.1`. |
| `proto_commit` | The definitions-repo commit at the time the version was created. |
| `build_commit` | The build-repo commit the version was built from; the image tag. |
| `branch` | The build-repo branch the commit was on, asserted by the client that ran the build (informational). |
| `created_by` | The user who ran the build. |
| `images[]` | Each image's `path` relative to the service (`.`, `worker`) and its state. |
| `state` | `BUILT`, `RETAGGED`, `BUILDING`, `FAILED`; an aggregation of the image states. |
| `logs_url` | The build logs. |
| `package_id` | The package id, for example `acme.sh.orders.v1`. |

Deleting a version does not delete its images but prevents the version number from being reused.

## Deployment

A service version deployed in a deployment environment.

| Field | Meaning |
|---|---|
| `version` | The stable version currently deployed, for example `1.0.54`. |
| `beta_version` | The beta version, when one is deployed. |
| `envs[]` | The deployment's own variables, excluding managed `ALIS_*` ones. |
| `state` | `RUNNING`, `DEPLOYING`, `DEPLOY_FAILED`, `PLANNING`, `PLANNED`, `PLAN_FAILED`, `PLANNING_DESTROY`, `PLAN_DESTROY_FAILED`, `PLANNED_DESTROY`, `DESTROYING`, `DESTROY_FAILED`, `DESTROYED`. |
| `logs_url` | The deploy logs. |
| `operation` | The current or last long-running operation. |
| `package` | The contract package this deployment serves. |
| `created_by` | The user who last deployed; empty when a service account did (auto-deploy). |
| `feature_freeze` | When true, every deploy, plan and destroy of this deployment is refused with `DEPLOYMENT_FROZEN`. Only a product admin can change it, on its own, and changing it leaves `update_time` alone. |

A DeploymentVersion records each deploy of a deployment.

## Package ids

A service's package id `<org>.<product>.<path>.<vN>` maps deterministically to its resource name and folders. See [Package ids and folders](https://docs.alisx.com/reference/dbd/package-ids-and-folders.md).