Skip to main content

ADR-0200: Navin Enterprise Commercial and Omnichannel Sales Agent, a retail product layer on top of the Control Plane

  • Status: proposed
  • Date: 2026-11-04
  • Use case: UC-11 (agent_uses_cases/11_Retail_Commercial_Vente_Omnicanale.md), retail sector
  • Links: ADR-0175 (RAG product), ADR-0180 (shared shell), ADR-0184 (Customer Operations Agent), ADR-0191 (Supply Chain model whose generic modules are copied), OPA package eai.retail_commercial (deploy/policies/opa/retail_commercial.rego), contracts contracts/v1/retail-commercial-omnicanal-action-request.schema.json and contracts/v1/retail-commercial-omnicanal-copilot-event.schema.json, template navin-retail-commercial-omnicanal-agent (published: false).

Context​

A merchant wants to advise its customers on its authorised channels (website, app, chat, messaging), search its published catalogue, compare products, read prices, promotions and availability, prepare a cart, obtain the explicit confirmation of the customer and then hand over the hosted checkout, transfer the conversation to an advisor, follow an order and prepare a return, without ever promising a price, a stock, a delay or a promotion the source has not confirmed, without letting a language model conclude a sale or a refund, and without profiling customers. The PIM, the price engine, the ATP, the OMS, the POS and the CRM remain the only sources of truth.

The board asks to reuse the Customer Operations Agent (Retail pack) for conversations and cases; that product exists only as a decision (ADR-0184) and an audit, without code.

Decision​

  1. Separate product, generic modules copied. FastAPI backend navin_omnicanal (port 8483, Redis 6404, web 3484 served by the shared shell ADR-0180), PostgreSQL schema omnicanal with tenant then project RLS on every table, outbox, append-only audit, idempotency keys. The generic modules of the UC-09 model are copied and adapted, never imported.
  2. Conversations and cases behind a port. A ConversationPort (retail/conversations.py) shaped after ADR-0184 (channel session, deduplicated events, verified customer context, handoff, service case) with a minimal local implementation in the omnicanal schema. No second Customer Operations product is built; when CO ships, the local implementation is replaced by a CO adapter without changing the API.
  3. Sources read with their freshness. Catalogue, prices, availability, promotions, customers and orders are read through declared connectors (capability table, read-only by default, navin-sandbox labelled as such). Every offer carries source, version, observation date and validity; it is re-read before the cart and before the checkout. An absent attribute stays unknown.
  4. Explainable recommendations. Explicit constraints then a documented score, rules versioned as data, protected attributes refused, sponsored placement flagged, an unavailable product never shown as purchasable.
  5. External effects through the Action Gateway only. Cart, checkout, return request and CRM note go through the gateway (Idempotency-Key, If-Match, OPA, OpenFGA, maker-checker for commercial gesture, refund, binding cancellation, marketing send and rule change). The checkout requires the explicit confirmation of the customer on the exact hash of the lines; the order is order_confirmed only on the answer of the OMS; an uncertain answer becomes unknown_pending_confirmation and the source is re-read before any retry.
  6. Marketing contact on recorded consent only, an opt-out revoking the related uses.
  7. Copilot on the runtime contract of the model: reads under RLS, preparations through the gateway, no execution by the LLM, SSE with Last-Event-ID, content of product sheets and connector answers treated as untrusted data; automatic suspension when an advisor has taken over.

Consequences​

  • Positive: product usable without CO, clear boundary for the migration to CO, no unconfirmed promise.
  • Negative: local implementation of conversations to migrate; no real connector (PIM, OMS, CRM, payment) is delivered; Shopify, WooCommerce, PrestaShop and Magento stay declared not configured.

Rejected alternatives​

  • Building a second Customer Operations product inside UC-11: refused (duplicate of ADR-0184).
  • Importing the code of the UC-09 model: refused (coupling between products).
  • Caching prices to speed up the checkout: refused (promise not confirmed by the source).