Core Concepts - Gradial Docs

These concepts form the working model for Gradial ACI. The most important distinction is between work in progress, approved work, content selected for publication, and the release currently serving visitors.

Content and frontend concepts

Concept	Meaning
Page	A route-backed content document composed from a layout and ordered component blocks
Fragment	Reusable content referenced by one or more pages or layouts
Component contract	A typed definition of the props and asset slots a component accepts
Layout contract	A typed definition of a page layout, including its regions, slots, and defaults
Registry	The project mapping that pairs contracts with their Astro or React runtime components
Overlay	A targeted change applied over base content for a dimension such as locale or audience
Code build	A versioned build of the frontend that can be linked to a branch and used for preview or release

Content contracts stay framework-neutral. Runtime components own framework imports, styling, and rendering behavior.

Versioning and approval concepts

Concept	Meaning
Version	An immutable saved state in ACI’s content history
Branch	An isolated line of work with its own content versions
`main`	The approved content trunk. Landing a branch here records approval but does not make the content live
Land	Apply an approved branch’s changes to `main` after conflicts and validation are resolved
`live`	The content trunk selected for the next site release
Promote	Move selected paths from `main` to `live`
Drift	The approved content in `main` that has not yet been promoted to `live`

A branch is not a version, and main is not the live website. Those distinctions make it possible to review a series of changes together, approve them, and still control when individual paths become public.

Compilation and delivery concepts

Concept	Meaning
Compilation	Validation and preparation of content against a specific code build
Release	An immutable, deployable set of site artifacts produced from `live` content and a code build
Stage	Prepare a release alongside the release currently serving traffic
Activate	Make a staged release current
Release rollback	Return traffic to a previously staged release as a whole
Preview	A branch-specific rendering of saved content with that branch’s linked code build

A content rollback and a release rollback solve different problems. To restore an individual path, select the intended earlier content version and publish a new release. To restore the entire site state, roll back the active release.

Personalization concepts

Concept	Meaning
Base experience	The default content served when no personalization applies
Segment	Membership criteria evaluated from allowed visitor signals
Audience	A targetable group used to select an experience
Experience	The content a visitor should receive for an audience or experiment arm
Variant	A compiled release artifact produced from a base experience plus its applicable overlay
Experiment arm	One of the experiences compared within an experiment

ACI evaluates audience eligibility at request time, but it does not build personalized content at request time. Base and variant artifacts are prepared during release compilation. Unknown, unconsented, or unmatched visitors receive the base experience.

Three boundaries to remember

Content and code

They have separate histories and are paired deliberately for preview and release.

Approval and publication

Landing moves work to main; promotion selects content for live; activation changes the site visitors receive.

Decision and rendering

ACI determines an eligible variant at the edge, then serves or renders that exact compiled artifact.

Next: Developer Quickstart →

​Content and frontend concepts

​Versioning and approval concepts

​Compilation and delivery concepts

​Personalization concepts

​Three boundaries to remember