Concept

How server-side constraint and rule evaluation works

One request per click, four steps in a fixed order, three possible answers.

, imagine.io ·

Every change a shopper makes is one mutation sent to the imagine.io constraints engine together with the full current state. The engine checks the catalog version, applies the matching rules, re-checks every constraint, prices the result, and answers with one resolved state. That is what makes it a constraints engine rather than a rules engine: rules shape the result, but nothing they do can break a constraint, so only valid configurations are ever built. The browser decides nothing; it renders the answer.

BrowserSDK, iframe oryour own pageone mutation+ the stateTHE ENGINE1Check the catalog version2Apply the mutation3Matching rules4Constraints, then price200 appliedresolved state + price409 catalog changedrefetch and retry422 rejectedreason, previous state keptstateless: every request carries the full current state BrowserSDK, iframe or your own pageone mutation + the stateTHE ENGINE1Check the catalog version2Apply the mutation3Matching rules4Constraints, then priceone of three answers200 appliedresolved state + price409 catalog changedrefetch and retry422 rejectedreason, previous state keptstateless: every request carries the full state
One request per click. The engine checks the version, applies the change, runs rules and constraints, prices, and answers one of three ways.

The request

Picking an option, adding or moving a product, swapping a variant, loading a preset: each is a mutation with a type and a payload. The request also carries the catalog version the page booted with and the whole current state, so the engine is stateless.

POST /evaluate/
{
  "systemId": 2,
  "catalogVersion": 939,
  "mutation": { "type": "selectSystemOption", "optionSetId": 18, "optionId": 160 },
  "state": { "selections": { "16": 179 }, "placements": [ "..." ] },
  "context": { "focus": { "placementId": "p_2", "variantId": 311, "componentId": null } }
}

Four steps, in order

  1. Check the catalog version

    If a newer catalog has been published since the page loaded, the engine stops here and answers 409. The SDK retries with the current version; the shopper never notices.

  2. Apply the mutation

    The change lands on the state. Unpicked selections are filled from their defaults, so rules always see a complete configuration.

  3. Run the matching rules

    A rule is when this, do that: hide or disable an option, swap or hide a part, load a material, add or remove a product, change a default, show a message, emit an event. Every rule whose trigger matches the new state fires.

  4. Re-check every constraint, then price

    A constraint is a limit that always holds: a maximum count, a required neighbour, a fixed position, a custom condition. If one fails, the engine answers 422 with the reason and keeps the previous state. Otherwise it prices the resolved configuration from the option prices and the channel's overrides.

Three answers

HTTPMeaningWhat the SDK does
200 appliedThe change was valid. The envelope carries resolvedState, pricing, the options now hidden or unavailable, messages, events and any products the cascade added or removed.Repaints from resolvedState, applies every effect, fires evaluate.completed then price.changed.
409 catalog changedA newer catalog was published while the shopper was configuring.Refetches the catalog and retries the same mutation once. Never surfaced.
422 rejectedA constraint refused it. code and errors[] say why; resolvedState and pricing are null.Rolls back the optimistic paint, keeps its state, toasts the reason, fires evaluate.rejected.

What comes back on a 200

  • resolvedState: the whole configuration after the cascade, every placement with its selections, the parts a rule swapped or hid (overrides), and which options each piece may take (bindings, one list per placement).
  • optionVisibility and optionAvailability: options a rule hid, and options a rule greyed out.
  • pricing: base price and adjustments per placement, unit prices, scene-wide adjustments and the grand total. The only price that counts.
  • messages, events, customEffects: what rules want shown, told to your code, or handled by a handler you registered.
  • addedPlacements and removedPlacements: products the engine added or removed as a consequence, with the reason.

The SDK documentation lists every field with its exact shape, when it is present, what the SDK already does with it and what is left for you.

Why on the server

A dealer portal, a marketplace listing and your own store all send the same request and get the same resolved state, from one catalog. A new finish added in the dashboard appears everywhere on the next load. And because the browser decides nothing, a custom interface built with the SDK cannot bypass a rule or a constraint, and the price the shopper sees is the price the engine returned, not a figure a page script added up.

Reading it in code

import { on, evaluation, useEvaluation } from '@imagineio/configurator-sdk';

// Push: at the moment of the answer
on('evaluate.completed', ({ mutation, pricing, messages }) => track('configured', { type: mutation.type, total: pricing.grandTotal }));
on('evaluate.rejected',  ({ mutation, code, errors })     => track('constraint_hit', { type: mutation.type, code }));

// Pull: the last answer, any time (in the console, this is how you debug a rule)
const last = evaluation.last();     // { kind, mutation, resolvedState, pricing, optionVisibility, durationMs, ... }
evaluation.explainOption(10, 102);  // why an option is not offered: 'hidden_by_rule', 'disabled_by_rule', ...

// React: re-renders on every evaluation
function EngineStatus() {
  const { last, pending } = useEvaluation();
  if (pending) return <span>Checking…</span>;
  return <span>{last?.rejected ? last.errors[0]?.message : last?.pricing?.grandTotal}</span>;
}

Frequently asked questions

Does the browser cache the rules and run them itself?

No. The frontend never re-derives a rule or a price. It sends the mutation with the current state and draws what the engine returns. Pricing and validity have exactly one source.

Can my page add a rule or change a price locally?

No, and that is the point. A custom interface built with the SDK can only ask the engine and show the answer, so it cannot bypass a rule or a constraint, and the price the shopper sees is the price the engine returned.

How does my code read the result?

Three forms of the same record: push, with on('evaluate.completed') and on('evaluate.rejected'); pull, with evaluation.last() and evaluation.history(); and React, with useEvaluation(). In an iframe the same events cross to the parent page as configurator:event messages.

Is the engine stateless?

Yes. Every request carries the full current state (selections and placements), so the engine needs no session and any instance can answer any request.

Why should configurator rules be checked on the server instead of in the browser?

A check in the browser can be skipped, cached or simply wrong, so an invalid product can still reach the cart. The imagine.io Configurator Platform evaluates every rule and constraint on the server on every change, so only valid configurations are ever built.

SDK documentation · Admin guide