Skip to main content

ADR-0204: Navin Enterprise Store Management and Performance Agent, retail product layer above the Control Plane

  • Status: proposed (2026-11-05)
  • Deciders: Navin Enterprise AI platform team, UC-15 mission (agent_uses_cases/15_Retail_Gestion_Magasins_Performance.md)
  • References: ADR-0180 (frontend shell), ADR-0191 (supply-chain model whose generic modules are copied), ADR-0174 (memory provider), OPA package eai.retail_magasins (deploy/policies/opa/retail_magasins.rego), OpenFGA fragment deploy/policies/openfga/products/retail-magasins-performance.fga, contracts contracts/v1/retail-magasins-performance-action-request.schema.json and contracts/v1/retail-magasins-performance-copilot-event.schema.json, Manager template navin-retail-magasins-performance-agent (published: false).

Context​

A store network wants to consolidate the indicators of each point of sale (net sales, margin, tickets, average basket, conversion, availability, returns, shrink, aggregated productivity), compare them like for like, detect gaps, prepare a diagnostic and action plans, follow their field execution and measure their effect. The brief requires eight modules (section 7), a server state machine (section 6), deterministic KPIs where absent data is never zero, and forbids any individual surveillance of employees.

Decision​

  1. Separate product navin-enterprise-retail-magasins-performance/, package navin_magasins, PostgreSQL schema magasins with RLS on every tenant table, prefix /api/v1/retail-magasins-performance, ports api 8487, redis 6408, web 3488 (rendered by the shared shell, ADR-0180).
  2. The generic modules of the supply-chain model (auth, authz, audit, Action Gateway, jobs, worker, documents, copilot, observability) are copied and adapted, never imported from another product.
  3. KPIs are computed deterministically from source data (POS, ERP, workforce, counters) with definitions versioned as data; amounts are decimal strings with currency, never summed across currencies; a zero or absent denominator makes the KPI not_available.
  4. Comparisons follow like-for-like rules (constant cohort, non-stable stores excluded and documented); anomalies are signals for a human, never a judgement of a person.
  5. Action plans are approved with maker-checker (the maker never approves, nor the copilot nor a robot) and then assigned through the Action Gateway with Idempotency-Key, If-Match and source confirmation; an uncertain answer becomes unknown_pending_confirmation.
  6. Effectiveness compares before and after, names confounders and stays observational without a control group: never presented as a proven causal effect.
  7. RAG and memory go through the Control Plane (knowledge API, memory provider of ADR-0174); no second engine.

Consequences​

  • Real connectors (POS, ERP, counters, workforce, task management) remain to be plugged; only a sandbox declared sandbox is exercised.
  • The template stays prepared and absent from the catalog until an explicit validation is given.