Blueprints

The Blueprints section of the Refinery Studio lets you browse the blueprint catalog of your environment, install or re-apply blueprints on the current tenant, and inspect what is already installed.

A blueprint is a versioned bundle of Construction Kit models plus seed data that puts a tenant into a working state. For the underlying mechanics see the tech guide: Blueprints.

Accessing the Blueprint Pages

Navigate to Repository → Blueprints in the tenant menu. Two views are available:

• Catalog — every blueprint available in the configured catalogs, with install / re-apply actions.
• Installations — every blueprint currently installed on the active tenant, with apply history and status.

Catalog View

The Catalog page renders each available blueprint as a card. The page header carries three filters that narrow the list:

Control	Purpose
Search	Substring match against the blueprint name and description.
Catalog	Limit to a single catalog source (LocalFileSystem, PublicGitHub, etc.) or show All.
Status	All / Installed / Not Installed / Updates available.

Each card shows:

• Blueprint name and version.
• Description from the blueprint manifest.
• Catalog source badge.
• Installation status — NOT INSTALLED, INSTALLED, or UPDATE AVAILABLE (when the catalog has a higher version than what is installed).
• Action button — Install, Re-apply (installed at the same version), or Update (newer version available).

Installing a Blueprint

1. Find the blueprint in the catalog. Use search / filters as needed.
2. Click Install on the card.
3. The confirmation dialog summarises what will happen: CK model dependencies are imported, seed data is applied via upsert. Confirm with Yes.
4. While the apply runs the card shows a spinner. The action is locked until the apply finishes.
5. On success a green toast appears: Installed <blueprint-id> — <N> seed file(s). If the apply produced warnings the toast appends (<n> warning(s)) and a details dialog opens automatically — see Reading Warnings below.
6. The card flips to INSTALLED and the action button changes to Re-apply.

Re-applying a Blueprint

Re-apply is the recovery path: it re-imports the seed data via upsert even though the blueprint is recorded at the same version. Use it when:

• You suspect seed entities were modified or partially deleted and you want them re-asserted.
• A previous apply landed seed entities but did not finish the history insert (legacy behaviour, fixed in the per-tenant storage rollout — see the tech guide).

The flow is identical to Install but the confirmation dialog reads Re-apply blueprint '<id>'? Existing seed entities will be upserted.

Reading Warnings

If the backend returned warnings during apply, the success toast appends a count and a details dialog opens automatically:

• Title — Blueprint apply warnings — <blueprint-id>
• Body — one bullet per warning, monospaced (whitespace preserved).
• Actions — Copy to copy the full list to the clipboard; Close to dismiss.

The dialog is resizable and non-blocking — the catalog refresh runs underneath while the dialog is open.

If a warning is unclear, copy the text and check the asset-repo logs for the corresponding ERROR / WARN entry around the timestamp of the apply.

Failure Modes

Symptom	Cause
Red toast Install failed: <message>	Backend rejected the apply. The message often carries a hard conflict, a missing CK dependency, or a YAML schema error.
Spinner stays forever	Network or backend stall. Reload the page; the apply may have completed server-side already.
Card stays on NOT INSTALLED after success	Stale cache. Switch to the Installations view to confirm; the catalog re-fetches on page enter.

Installations View

The Installations page lists every blueprint currently installed on the active tenant. Each row carries:

Column	Meaning
Blueprint	Name and version (HelloBlueprint-1.0.0).
Installed at	Timestamp of the first apply on this tenant.
Last updated	Timestamp of the most recent apply (install, update, re-apply, rollback).
Dependency	Yes when this blueprint was installed transitively to satisfy another blueprint's dependency, No when it was requested explicitly.
Seed checksum	Checksum of the last applied seed file (use to detect drift between catalog and tenant).

Two action buttons appear in the page toolbar:

• Refresh — re-fetch the installations from the backend.
• Apply History — switch to the chronological history view of all apply operations on this tenant.

Apply History

The history view is a chronological log of every apply operation (Initial, Update, Rollback, Reapply, Uninstall) with timestamps, the previous version (for updates and rollbacks), and per-operation entity counts:

Column	Meaning
Applied at	UTC timestamp of the apply.
Blueprint	Name and version that was applied.
Mode	Initial / Update / Rollback / Reapply.
Previous version	The version that was installed before this apply (empty for Initial).
Created	Number of seed entities created.
Updated	Number of seed entities updated.
Deleted	Number of seed entities deleted.

History is append-only — there is no edit/delete in the UI. The retention is per-tenant: when a tenant is deleted, its history goes with it.

Where the Data Lives

Both the installation rows and the history entries are stored as Construction Kit entities in the tenant's own runtime repository — there is no central registry. This matters in practice for two scenarios:

• Tenant backup — mongodump --db=<tenant> captures the blueprint state along with the seed entities.
• Tenant deletion — dropping a tenant deletes the blueprint history along with it. There is no "ghost history" left in a system database.

See Also

• Blueprints (Tech Guide) — full mechanics, schema, lifecycle
• octo-cli — the same operations from the command line