Your domain APIs know everything. You’re still leaving the frontend to do all the thinking.
Most enterprise applications already know how to aggregate data. What they don’t know is what to do with it.
Consider a large enterprise building a self-service portal. Every domain API is clean. Every microservice has solid ownership. The BFF faithfully merges payloads from domain services such as orders, profiles, permissions, entitlements, and notifications. But within a user’s own role and permissions, the system still cannot explain what it already knows in a way the user can act on. The data is all there. The intelligence is not.
This is often the default outcome of aggregation-only architectures. Enterprise systems are organized by domains, but users arrive with goals.
They do not think, “I need data from the orders API, the permissions API, and three other systems.” They think, “What changed in my account?” or “What do I need to do next?”
That gap between domain-organized data and goal-oriented experience is where a stronger architectural pattern becomes necessary.
The Problem Is Not Data. It Is Interpretation.
Aggregation solves more than just data collection. A well-built aggregation layer delivers a predefined, contract-agreed composition of domain payloads for known use cases. That is real architectural value. But it stops at the boundary of what was already defined. It does not answer, “How do I turn that data into an experience-ready response for this user, in this context, for this goal?” when that goal was not anticipated at contract design time.
Without that interpretation layer, the frontend absorbs cross-domain reasoning responsibility it was never meant to own: interpreting domain outputs, deciding what matters most, explaining why actions are blocked, prioritizing which widgets to show first, and creating coherence across backend services that were never explicitly modeled to work together at the experience level.
A page may load successfully and still feel unintelligent.
An aggregator delivers what the contract already defines. An orchestrator helps the system decide what that data means in context.
The Missing Middle Layer: Experience Orchestration
Within a user’s own roles and permissions, there is often more the system can explain, connect, or surface than predefined aggregation can cover. An experience orchestrator addresses that gap. It composes domain capabilities, resolves journey context, applies deterministic rules, and optionally uses AI to interpret what the system already knows, without pushing that interpretation logic into the frontend.
Where an aggregator combines payloads for predefined use cases, an orchestrator combines payloads with context, rules, and presentation intent. It answers intelligence needs that would otherwise force the frontend to wait for another endpoint, another contract, and another round of backend coordination.
This is especially relevant in enterprise systems where domain APIs are clean but narrow, and user journeys cross multiple domains. The frontend must still present one coherent experience, while teams preserve strong ownership boundaries underneath.
Why Orchestration Succeeds Where Aggregation Stops
This pattern matters when the gap between what domain APIs provide and what the user actually needs cannot be closed by aggregation alone.
Most enterprise teams already have clean domain services. The constraint is not missing data. It is that composing cross‑domain context, resolving intent, and shaping a coherent response requires coordination that no single domain service owns. Adding that logic to the frontend creates tight coupling. Adding it to a BFF creates scope creep. Neither option scales well across journeys.
An experience orchestrator offers a different approach: it composes existing domain capabilities, interprets the current context, and shapes a response that reflects what the user is actually trying to do. The critical advantage is that none of this requires structural changes to the domain services underneath. They remain clean, narrowly scoped, and independently owned. The intelligence lives in the orchestration layer, not in the services it calls.
Designing the Contract with OpenAPI
The central design question is simple: how does a smart orchestrator stay predictable for the frontend?
The answer is a fixed response envelope. Every response from the orchestrator follows the same shape, every time. What varies is the content inside that shape: which sections appear, which actions are available, and what messages are included. The orchestrator is adaptive internally. Its public contract is not.
Think of it like a shipping container. The container dimensions never change. What goes inside depends on the shipment. The frontend knows exactly how to unload the container because the shape is always the same.
A typical request carries user context, page context, object references such as order ID or account ID, optional intent hints, and optional natural-language input. A typical response follows a stable structure: requestId, status, resolvedIntent, sections[], actions[], messages[], and errors[].
The real power comes from how sections and actions are modeled.
Sections are typed variants: OrderSummarySection, PermissionsSection, DelayReasonSection, ResolutionSection, AlertSection, GuidanceSection. Each section has a type field that tells the frontend exactly what it is. In OpenAPI terms, this can be modeled with oneOf and a discriminator: the contract defines every allowed section type, while the orchestrator includes only the ones relevant to the current context. The contract stays strict. The response stays flexible.
Actions work the same way. Instead of returning vague strings the UI has to interpret, the orchestrator returns explicit action objects: TRACK_SHIPMENT, CONTACT_SUPPORT, REQUEST_ACCESS, REQUEST_REFUND. Each carries a type, label, enabled flag, reasonIfDisabled, target, and metadata. The frontend does not decide what actions are available. The orchestrator does.
Errors and warnings are modeled structurally: UPSTREAM_TIMEOUT, PARTIAL_DATA, UNAUTHORIZED, ENTITLEMENT_BLOCKED, UNSUPPORTED_INTENT. This matters because orchestrators often produce partial success rather than simple pass/fail. A response might include two healthy sections, one timed‑out section, and a warning. The contract should reflect that reality rather than forcing a binary success or failure.
To make this concrete:
{
"requestId": "req_8x92k",
"status": "SUCCESS",
"resolvedIntent": "ORDER_STATUS_REVIEW",
"sections": [
{
"type": "OrderSummarySection",
"orderId": "ord_20456",
"status": "DELAYED_IN_TRANSIT",
"estimatedDelivery": "2026-04-08"
},
{
"type": "DelayReasonSection",
"cause": "CARRIER_DISRUPTION",
"explanation": "Shipment delayed..."
},
{
"type": "ResolutionSection",
"autoRerouted": true,
"supportTicketId": "tkt_9281",
"summary": "Proactive rerouting applied..."
}
],
"actions": [
{ "type": "TRACK_SHIPMENT", "enabled": true, "label": "Track updated route" },
{ "type": "REQUEST_REFUND", "enabled": false, "reasonIfDisabled": "Eligible after 7 days" }
]
}Notice how the envelope shape is identical whether the user is checking an order, reviewing a delay, or tracking a resolution. The frontend renders sections by type, displays actions with their enabled or disabled states, and shows messages and errors. No new UI logic is needed to consume smarter responses, only the same contract-aware rendering logic the frontend was already built to use.
The orchestrator does the interpretation. The contract carries the result. The frontend renders what it receives.
Where AI Actually Fits
This is the most important architectural boundary in the pattern.
The most expensive orchestrator failures happen when teams use AI to replace domain services, redefine authorization, or act as the contract itself. That kills observability, breaks audit trails, and makes the system undebuggable when the model drifts.
Instead, AI is used selectively inside the orchestrator, in bounded, well‑defined places.
Intent Interpretation
A user may arrive with a natural question or an ambiguous goal. The orchestrator uses AI to classify the request: what journey the user is in, which explanation category applies, which downstream services are relevant, and which response sections should be prioritized.
Contextual Analysis After Retrieval
Once deterministic retrieval completes, the orchestrator has structured outputs from several domain APIs. AI helps analyze that context to answer what matters most, what likely explains the current issue, what should be emphasized first, and what summary would be most useful.
Response Shaping
AI transforms structured facts into a plain-language explanation, a ranked list of next steps, a concise summary, or a prioritized presentation order for the UI.
Critical: The final response is still translated into typed structures, not handed off as uncontrolled free text. The model is called inside the orchestration flow, not instead of the flow.
What Must Remain Deterministic
A serious enterprise architecture must be explicit about where AI stops.
These concerns remain deterministic: systems of record, domain truth, entitlements, authorization, policy enforcement, state transitions, transaction execution, and irreversible actions.
AI may help interpret or explain those things, but it should not silently override them.
Deterministic systems decide truth. AI helps interpret truth.
In practice, deterministic APIs and AI classification will occasionally disagree. When the model suggests a user qualifies for expedited resolution but the Entitlements API says their tier does not include it, the deterministic domain system wins. The orchestrator should log the conflict for analysis (it may reveal genuine edge cases or model drift) but it should never let AI insight override domain truth. In regulated environments, the audit trail must show that the system of record made the decision, not a model.
The same principle applies when two domain systems disagree. For example, when the Entitlements API says “blocked” but the Order API says “active.” The orchestrator should log the conflict for analysis, because it may reveal genuine edge cases or model drift, but it should never let AI insight override domain truth.
A Concrete Example: Order Status During a Fulfillment Delay
A user visits their order details page. Nothing unusual from their perspective. They are just checking status.
The UI sends a request to the experience orchestrator with user context, order ID, and page context. No question asked, no special input required.
The orchestrator fans out to five domain APIs: Order, Logistics, Entitlements, Communication History, and Account.
Individually, each response looks straightforward. Order exists. Shipment is in transit. Account is active. But Logistics reports a carrier disruption with a revised delivery estimate. Entitlements confirms that the user’s account tier includes proactive rerouting. Communication History shows that a support ticket was already opened automatically two hours ago.
An aggregator would return all five payloads and leave the frontend to display them in separate widgets. The user would see “In Transit” in one place, a delayed estimate somewhere else, and have no idea a support ticket already exists or that their account tier triggered automatic rerouting.
The orchestrator resolves the cross-domain context: it connects the delay with the account tier benefit, surfaces the existing support ticket, and determines the most useful next steps for this specific user.
An AI step is invoked: generate a plain‑language summary of the situation, prioritize the available actions, and determine which sections should appear first.
The orchestrator converts that intelligence into a typed response:
- resolvedIntent: ORDER_STATUS_REVIEW
- sections[]: OrderSummary, DelayReason, Resolution
- actions[]: TRACK_SHIPMENT, CONTACT_SUPPORT, REQUEST_REFUND (disabled: eligible after 7 business days)
- messages[]: “Shipment delayed due to carrier disruption. Proactive rerouting applied based on your account tier. Support ticket tkt_9281 is already open.”
The UI receives a stable, contract-defined response. Not raw AI output or a pile of disconnected domain payloads, but a coherent, proactive explanation the user never had to ask for.
Handling Latency: Core First, Intelligence Second
Orchestrators must respond quickly. Model calls can take seconds. That tension is real, and ignoring it will kill adoption faster than any technical limitation.
The design principle is straightforward: the deterministic path always completes first. The orchestrator returns core sections and actions immediately based on what domain APIs provide. AI enrichment arrives after first paint, either streamed progressively or fetched as a follow-up.
In the fulfillment delay example, the order summary, delay reason, and available actions can all be resolved deterministically from domain API responses alone. The AI‑generated plain‑language summary and prioritized action ordering arrive as enrichment. If the model is slow or unavailable, the user still sees a complete, useful response. They simply miss the polish.
This is not a novel UX pattern. Incremental client reconciliation, async request/polling for long‑running work, and progressive AI‑enriched responses are all established approaches in modern API and frontend design. The deterministic orchestrator response serves as the initial authoritative payload. AI enrichment arrives as a typed follow‑up update against the same contract model, not as an uncontrolled second response.
For high‑value or high‑frequency journeys, selective precomputation is another option. If a shipment status changes, the orchestrator can precompute the enriched response before the user even visits the page. This works best for recently changed entities, premium account flows, and high‑frequency support scenarios where reuse and latency sensitivity justify the cost.
Not Every Journey Needs the Same Intelligence
Every user receives the same deterministic, contract-driven foundation. But not every request justifies the same compute cost.
A straightforward order status check with no delays or cross-domain complexity may need no AI at all. A more complex scenario like the fulfillment delay example, where multiple domain APIs contribute conflicting signals and the user’s account tier affects what resolution is available, benefits far more from classification and explanation generation.
The orchestrator should be designed so that intelligence is additive, not mandatory. AI enrichment belongs where the complexity warrants it: exception handling, multi-domain queries where cross-cutting context matters, or flows where a plain-language explanation materially improves the user’s ability to act.
This is an architectural decision, not a pricing decision. The question is where AI adds signal versus where it adds latency for no gain.
Observability: Knowing Whether the Orchestrator Is Working
The orchestrator becomes a single point of interpretation. If it times out, returns partial data, or drifts from its contract, the frontend has no fallback. The user sees a broken experience while backend logs show nothing wrong. That is why observability here is different from observability everywhere else.
Four things matter most. First, orchestrator-induced latency: the time the orchestrator adds on top of raw domain API response time, measured as a percentile distribution rather than just an average. Second, intent resolution accuracy: how often the resolvedIntent matches what the user actually needed, measured through action click‑through rates or periodic classification review. Third, section utilization: which response sections the UI actually consumes versus which are computed but ignored. Fourth, partial‑response rate: how often the orchestrator returns a usable but incomplete response because one or more downstream systems timed out. This metric reveals whether graceful degradation is actually working or silently eroding the experience.
The orchestrator should also propagate trace context through every domain call and AI invocation. Without end‑to‑end tracing, debugging a slow or incorrect response requires guesswork across team boundaries, exactly the kind of problem the orchestrator was designed to eliminate.
When This Pattern Does Not Apply
Not every system needs an orchestration layer.
Simple read-only portals that display data from a single domain do not need an orchestrator. They need a clean API.
High-frequency, low-latency pipelines where every microsecond matters should not add an interpretation layer between source and consumer.
Systems where the user journey never crosses domain boundaries gain little from cross-domain composition.
The pattern earns its complexity when the experience spans multiple domains, user intent requires interpretation, and the frontend would otherwise absorb composition logic it was never designed to handle.
Why This Pattern Matters Now
The next step beyond aggregation is not making APIs looser. It is making orchestration smarter while keeping contracts strict.
A contract‑driven experience orchestrator gives enterprises a way to preserve clean domain ownership, keep the UI predictable, translate user goals into cross‑domain responses, and introduce AI where it actually adds value: inside the orchestration flow, not in place of it.
Most enterprises already have the domain services. They already have the data. What they do not have is a layer that connects those capabilities into something the user can actually understand and act on, without rewriting the services underneath or overloading the frontend with logic it was never meant to carry.
The strongest enterprise systems of the next few years will not be the ones that embed AI into every layer. They will be the ones that understand where intelligence belongs, where determinism must remain, and how to connect the two through a well-designed contract.
The pattern is simple: deterministic systems decide. AI interprets. Contracts enforce.
Beyond Aggregation: Contract-Driven Experience Orchestration was originally published in Towards AI on Medium, where people are continuing the conversation by highlighting and responding to this story.