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

# How Gradial ACI Works

> Follow an ACI change from an isolated branch through validation, approval, promotion, and release.

ACI keeps authoring, approval, and delivery separate. A team can iterate on content and code without affecting the live site, then move only approved work through a controlled release.

## The path from draft to live

```mermaid theme={null}
flowchart LR
    A["Work on a branch"] --> B["Validate and preview"]
    B --> C["Land on main<br/>approved"]
    C --> D["Promote to live<br/>selected paths"]
    D --> E["Stage a release"]
    E --> F["Activate"]

    style A fill:#6366f1,color:#fff
    style C fill:#8b5cf6,color:#fff
    style F fill:#22c55e,color:#fff
```

### 1. Model the site

Your ACI project defines:

* A `.aci.yaml` project configuration
* Component contracts that describe valid props
* Layout contracts that describe regions and slots
* Runtime components that render those contracts in Astro or Next.js
* Structured content for pages, fragments, configuration, and overlays

Contracts are the boundary between content and code. They let ACI check whether a page can be rendered by the code build selected for it.

### 2. Work on a branch

Content changes happen on a branch, separate from `main` and `live`. A branch can contain one page change or a coordinated set of updates across many paths.

When code and content need to change together, link the branch to the intended code build. Preview and validation then evaluate the combination reviewers are considering, rather than an unrelated version of the site.

### 3. Validate and preview

ACI checks content structure, component props, references, routes, layouts, and overlays against the frontend contracts. Diagnostics identify the content path and field that need attention.

A branch preview renders its saved content with its linked code build. Preview is for visual and functional review; successful compilation remains the release gate.

### 4. Approve, then choose what goes live

Landing a branch moves its approved changes to `main`. It does not publish them.

Promotion moves selected paths from `main` to `live`. This lets a team approve a coordinated body of work, then release the relevant paths on its own schedule. ACI can also show the difference between `main` and `live` so approved-but-unpublished changes remain visible.

### 5. Compile a release

ACI compiles the `live` content state with the selected code build. It validates the complete release input and produces immutable artifacts for each route and configured variant.

| Delivery mode | Release output |
| - | - |
| Static delivery | Complete HTML artifacts |
| Supported Next.js server rendering | Validated page data for the exact variant selected before rendering |

Personalization does not change the approval flow. ACI compiles the base experience and configured variants as part of the same release. At request time, edge delivery selects an eligible artifact; if none applies, it serves the base experience.

### 6. Stage and activate

Staging prepares a complete release without changing customer traffic. Activation makes that release current as one operation, so visitors are not split across partially updated releases.

If the release has a problem, release rollback returns traffic to an earlier staged release. If only a content path needs to change, restore or promote the intended version of that path and create a new release.

## Code and content stay coordinated

Content versions and code builds have separate histories, but ACI evaluates them together at preview and release time. This gives developers room to evolve components while content teams continue working, without weakening the contract between them.

***

*Next: [Core Concepts →](/aci/getting-started/core-concepts)*


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.