--- title: "Projects & Components" canonical: "https://admiral.io/docs/concepts/projects-and-components" description: "Admiral's ownership hierarchy: projects group environments like dev and prod, and each component is the per-environment desired state you own and change." --- # Projects & Components A **Project** groups related work into **Environments** like dev and prod, and a **Component** is a single thing you deploy into one environment. The Component is the per-environment desired state you own and change. ## The ownership hierarchy ```mermaid flowchart LR A["Project"] --> E["Environment"] --> C["Component"] ``` * A **Project** groups related work: a service, a stack, or a product area. * An **Environment** is a deployment target within a project: dev, staging, prod. Each is independent and carries its own variables. * A **Component** is a single deployable unit within one environment. Deploy the same thing to dev and prod and you get **two independent components**, each with its own per-environment values. A change to one does not touch the other. ```bash admiral project create checkout admiral env create checkout/prod ``` ## Component A Component is the per-environment desired state. It is the unit a deployment acts on, and it is **self-contained**: it carries its own definition instead of linking back to a shared template. A component carries: * the **Source** to fetch from, with the **ref and path** within it * the **engine** that deploys it * its **kind** (`infrastructure` or `workload`) * its per-environment **values** * its **dependencies** on other components * its declared **inputs and outputs** * its **target**, the agent that executes it Because the component carries its own definition, "what will this environment deploy?" is answerable from the environment's own data, with no chase to a shared template that might have moved. ### Component kinds A component's kind determines which execution path deploys it: | Kind | Engines | Executes via | | ---------------- | --------------------------- | ---------------- | | `infrastructure` | terraform | Terraform agent | | `workload` | helm / kustomize / manifest | Kubernetes agent | This is covered in depth in [Agents & Execution](https://admiral.io/docs/agents.md). ### Dependencies and the graph Components in an environment form a dependency graph. A component declares the components it depends on, and a deployment uses that graph to order work: upstream components apply first, their outputs are captured, and downstream components render against those outputs before they apply. This is how a database component can hand a connection string to an application component without you wiring it by hand. See [Variables & Outputs](https://admiral.io/docs/concepts/variables-and-outputs.md). ## You never edit a Component directly This is the most important rule in the model. A Component is mutated **only** through a [Changeset](https://admiral.io/docs/concepts/changesets-and-runs.md). There is no "edit this component" action that takes effect immediately. Every change (creating a component, changing its values, destroying it) is staged as a reviewable Change, planned, and applied. The live state of an environment only ever moves forward through that gate. > **Note:** A Change that creates a component pins a revision from the [registry](https://admiral.io/docs/concepts/registry.md), authored in the changeset or copied from another environment's changeset (promotion). Both produce the same self-contained component. ## Lifecycle: destroy and orphan Removing a component from an environment is itself a staged Change, with two distinct intents: * **destroy**: tear down the real resources, then remove the component * **orphan**: stop managing the component but leave the real resources in place Both flow through the same changeset-plan-apply cycle as any other change, so a teardown is as reviewable as a rollout. ## Where to go next * [Variables & Outputs](https://admiral.io/docs/concepts/variables-and-outputs.md): How values and cross-component data feed rendering