Concept
How server-side constraint and rule evaluation works
One request per click, four steps in a fixed order, three possible answers.
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.
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
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.
Apply the mutation
The change lands on the state. Unpicked selections are filled from their defaults, so rules always see a complete configuration.
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.
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
| HTTP | Meaning | What the SDK does |
|---|---|---|
200 applied | The 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 changed | A newer catalog was published while the shopper was configuring. | Refetches the catalog and retries the same mutation once. Never surfaced. |
422 rejected | A 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).optionVisibilityandoptionAvailability: 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.addedPlacementsandremovedPlacements: 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>;
}Related
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.