DecisioQ is deployed as a small set of cooperating services. Client applications authenticate, discover governed decision metadata, submit options, and receive a deterministic result without needing to manage catalog content or scoring infrastructure.
| Component | Primary responsibility | Public production host |
|---|---|---|
| Client App | Business UI, integration workflow, token storage, catalog selection, option entry, and result display. | Customer application or hosted demo site. |
| Identity Service | Authenticates DecisioQ API consumers and issues bearer tokens for secured calls. | https://identity.vinquery.com |
| Decision Catalog | Customer-facing catalog of sectors, categories, decisions, criteria, profiles, scenarios, and examples. It is implemented by the DecisioQ Knowledge Server (DKS). | https://dks.vinquery.com |
| Decision Service | Customer-facing decision-execution capability. It is implemented by the DecisioQ Decision Engine (DDE), which validates requests, applies scoring, and returns results. | https://dde.vinquery.com |
The Identity service issues access tokens for DecisioQ API consumers. Client applications request a bearer token from Identity and attach that token to catalog and decision calls.
- Production:
https://identity.vinquery.com/connect/token - Boundary: DecisioQ catalog and execution services validate incoming tokens but do not issue tokens.
The Decision Catalog is the source for decision metadata. Its internal serving component is the DecisioQ Knowledge Server (DKS). It answers questions such as which sectors exist, which categories belong to a sector, which decisions belong to a category, and which criteria, profiles, scenarios, and examples belong to a decision.
- Catalog:
https://dks.vinquery.com/decisioncatalog - Decision detail:
https://dks.vinquery.com/decisioncatalog/decisions/{decisionId} - Boundary: the Decision Catalog stores decision metadata. It does not run the recommendation.
The Decision Service receives validation and execution requests. When it needs catalog metadata, it calls the Decision Catalog using the propagated bearer token, then runs the deterministic decision model.
- Validation:
https://dde.vinquery.com/api/v1/validate - Business Data Mode or Prepared Criteria Mode execution:
https://dde.vinquery.com/api/v1/decide - Business-data execution:
https://dde.vinquery.com/api/v1/decide - Outcome feedback:
https://dde.vinquery.com/api/v1/decision-outcomes - Outcome reporting:
https://dde.vinquery.com/api/v1/decision-outcomes/summary - Boundary: the Decision Service computes recommendations and records account-scoped observed outcomes. It does not own public catalog metadata, and outcome feedback never changes scoring automatically.
The same bearer token follows the request across service boundaries so authorization, traceability, and account context remain tied to the original API consumer.
- The client requests a token from Identity.
- The client sends the token to the Decision Service for validation or execution.
- When decision metadata is needed, the Decision Service forwards the bearer token to the Decision Catalog.
- The Decision Catalog validates the token and associates catalog activity with the same account context.
- The Decision Service completes execution and returns the recommendation to the client.
| Step | Caller | Service | Outcome |
|---|---|---|---|
| 1 | Client app | Identity | Bearer token is issued. |
| 2 | Client app | Decision Catalog | Catalog, sectors, categories, and decision metadata are loaded. |
| 3 | Client app | Decision Service | Decision request is submitted for validation or execution. |
| 4 | Decision Service | Decision Catalog | Decision definition is retrieved using token propagation. |
| 5 | Decision Service | Decision Service | Options are validated and scored. |
| 6 | Decision Service | Client app | Recommendation, ranking, explanation context, warnings, diagnostics, and the durable decision receipt are returned. |
Every successful execution returns an always-present decisionReceipt. It freezes the identifiers and versions, normalized evidence, criteria and weights, applied rules, exclusions, ranking contributions, findings, and duration used for that result. The SHA-256 integrity hash makes later changes to that evidence detectable.
Persist the complete receipt unchanged beside the business transaction. correlationId joins the decision to the surrounding workflow; executionId identifies one engine run. Errors do not receive a receipt because no decision result was produced.
Both public request modes converge on the same authoritative Decision Catalog definition and deterministic Decision Service execution pipeline.
| Mode | Preparation boundary | Execution path |
|---|---|---|
| Business Data Mode | The selected Decision Preparation Model maps application facts into decision criteria, then catalog rules validate the prepared input. | The Decision Service applies the effective configuration, constraints, normalization, weights, and ranking algorithm before returning the result. |
| Prepared Criteria Mode | The caller supplies decision-ready option values; the Decision Service still validates them against the current catalog definition. | Validated criteria enter the same constraints, normalization, scoring, ranking, and response pipeline. |
The Decision Catalog owns definitions and preparation metadata; the Decision Service owns validation and recommendation execution. A client or gateway owns secret storage, user workflow, business-data collection, and result presentation.
| Service | Production endpoint | Primary use |
|---|---|---|
| Identity | https://identity.vinquery.com | Token issuance. |
| Decision Catalog | https://dks.vinquery.com | Catalog and decision metadata. |
| Decision Service | https://dde.vinquery.com | Validation and decision execution. |
| Client site | Hosted website or customer application | User workflow and integration experience. |
- Token issuance boundary: only Identity issues tokens.
- Catalog boundary: the Decision Catalog owns catalog and decision metadata.
- Execution boundary: the Decision Service owns validation, scoring, execution, and result generation.
- Client boundary: browser pages should not expose secrets. Server-side integration layers may be used to keep credentials and private settings off the public page.
- Diagnostics boundary: business pages should keep diagnostics collapsed or hidden by default; developer pages may expose request summaries, correlation IDs, execution traces, and service messages.
| Component | Architectural responsibility | Boundary |
|---|---|---|
| Integration Platform | Maps supported Business Data contracts into decision-ready criteria, coordinates validation, and exposes integration-facing metadata. | It does not own the deterministic ranking algorithms or the authoritative catalog. |
| Business Decision Studio | Authors, validates, tests, versions, publishes, and governs decision definitions, criteria, weights, algorithms, Profiles, and Scenarios. | Authoring is separate from runtime customer requests. |
| API Gateway / public service boundary | Terminates public traffic, applies routing and transport policy, and forwards authorized requests to Identity, DKS, DDE, or Integration Platform capabilities. | It does not calculate recommendations or redefine decision knowledge. |
| DKS | Publishes the governed runtime catalog and decision definitions. | It serves knowledge; it does not execute rankings. |
| DDE | Validates and deterministically executes the selected decision definition. | It executes knowledge; it does not author or publish it. |
The public contract remains stable across supported deployment arrangements. Production commonly separates Identity, DKS, DDE, Integration Platform, and authoring responsibilities so each can be secured, scaled, deployed, and monitored independently.
- Public managed services: clients call the published Identity, DKS, and DDE hosts through server-side integrations.
- Server-side proxy: a customer backend owns credentials, token reuse, retry policy, and browser-safe API exposure.
- Private connectivity: network controls may restrict service access without changing decision IDs or public payload contracts.
Deployment-specific host names, secrets, firewall rules, private endpoints, and production connection details belong in protected operational configuration, not public documentation or client source.
- Scale stateless API instances horizontally behind the gateway or load balancer.
- Cache JWTs until shortly before expiry and cache stable catalog metadata with an explicit refresh policy.
- Keep DDE execution deterministic and idempotent from the caller's perspective; use correlation IDs to distinguish retries.
- Monitor Identity, DKS, DDE, data stores, latency, error rates, dependency health, and catalog-version consistency independently.
- Use redundant instances and health-based routing; do not treat a successful gateway response as proof that every downstream dependency is healthy.
- Plan recovery for catalog publication, runtime configuration, and databases separately from application binaries.
Localization and measurement conversion belong at the integration boundary. DecisioQ keeps technical identifiers stable and evaluates the canonical values required by each decision definition. Unless an endpoint explicitly documents unit conversion, the consuming application performs that conversion before submission.
| Client application | Displays localized labels, collects explicit source units, converts to required canonical units, and formats returned values. It sends presentation or jurisdiction context only when the endpoint contract explicitly supports it. |
|---|---|
| Integration Platform | Maps Business Data into decision criteria. It validates or converts units only where the selected endpoint and schema explicitly document that behavior. |
| Decision Execution service | Scores canonical values deterministically. Presentation choices do not alter ranking or recommendation. |
| Trace and diagnostics | Preserve request and correlation identifiers plus any conversion metadata maintained by the consumer or explicitly returned by a supported endpoint. |
Canadian and US deployments can use different presentation defaults while preserving the same API identifiers. Equivalent real-world inputs should produce equivalent behavior after consumers convert them to the same canonical requirements.
Use Decision Concepts for modeling terminology. Use the Developer Center and API Guide for implementation details. Use the Business Decision Studio or Interactive Playground to exercise the live flow.