Skip to main content

ADR-0176: Navin Enterprise Banking Back-Office Automation Agent, banking operations product layer on top of the Control Plane

  • Status: proposed on 2026-11-04, awaiting the validation of the user (see "Points to validate")
  • Date: 2026-11-04
  • Scope: new project navin-enterprise-banking-backoffice/ (FastAPI backend, workers, Next.js 16 frontend, Navin integration), additive types of the OpenFGA model (deploy/policies/openfga/model.fga), OPA package eai.banking_backoffice (deploy/policies/opa/banking_backoffice.rego), contract contracts/v1/banking-action-request.schema.json, Navin Manager agent template prepared but not published
  • Related documents: ADR-0101 (licence policy), ADR-0103 (vLLM and LiteLLM), ADR-0108 (Opik), ADR-0166 (declared high availability, ClamAV and YARA-X), ADR-0171 (hardened installation), ADR-0173 (separation of the Manager and of Enterprise), ADR-0174 (Mem0 and Cognee memory), ADR-0175 (Navin Enterprise RAG Agent, reused pattern), audit navin-enterprise-banking-backoffice/docs/en/NAVIN_INTEGRATION_AUDIT.md, brief agent_uses_cases/00_Banking_Back_Office_Automation_Agent_Prompt.md

Context​

The customer asks for a complete banking back-office application: work queues, payment and settlement operations, reconciliation engine, suspense and exceptions, document instruction processing, controlled fees and corrections, end-of-day console, operational controls, reports and AI copilot, installable by the Navin Manager as a service template in pre-publication.

The audit of 2026-11-04 shows that the platform already provides, under governance: identity and tenant and project context (eai.auth.Principal, fail-closed require_relation), the tool gateway (POST /v1/tools/{name}/invoke with OPA decision, DLP and approval), approvals with separation of duties and idempotency key, dated and revocable delegations, mandatory file analysis (quarantine, ClamAV, YARA-X), knowledge bases (Docling, Qdrant), memory (Mem0, Cognee), connectors with a secret broker, the transactional outbox and the worker, OpenTelemetry and Opik traces, Prometheus metrics and the chained audit. The RAG product (ADR-0175) shows the pattern of a product layer on top of the Control Plane, with RLS, SSE, BFF and an unpublished descriptor.

All the banking business is missing: no reconciliation engine, no suspense, no source system confirmation, no delegation matrix by amount, currency, rail and authority level, and none of the neighbouring modules cited by the brief (Customer Operations, Compliance & Audit, KYC/AML, Credit Analysis) exists in the repository.

Decision​

1. A product layer, not a second platform​

WhoDoes what
Navin Managerinstalls and operates the runtime (API, workers, web), its dependencies, TLS, health, backups, upgrades, rollback; shows the template in the Agents tab with status prepared
Control Planeidentities, tenants, projects, roles, OpenFGA, OPA, approvals, delegations, tools, models through the LiteLLM gateway, file analysis, knowledge, memory, secrets, quotas, audit, traces
UC-00 backendbusiness objects (queues, cases, observed payments, reconciliations, suspense, exceptions, instructions, adjustments, EOD, controls, reports, conversations), Action Gateway, reconciliation engine; calls the Control Plane only through the Python SDK enterprise_ai

No second IAM, no own LLM gateway, no third tracing solution: the backend never calls Keycloak directly for anything but the verification of its tokens, nor LiteLLM, Qdrant, Cognee, Docling, ClamAV or YARA-X.

2. The systems of the bank remain the only sources of truth​

The core banking, the payment hub, the clearing networks and the general ledger (GL) are the only sources of truth of statuses, balances and entries. The PostgreSQL schema banking_backoffice keeps cases, proposed entries, status snapshots (payment_status_snapshots, reconciliation_source_snapshots), references (ledger_entry_refs, subledger_entry_refs) and workflow journals: these are timestamped and versioned investigation caches, never an official ledger. No table is presented as a second set of books; every effective entry comes from the GL through an approved connector, with an immutable reference and a posting proof.

3. Action Gateway​

Every side-effect action on a banking system goes through the Action Gateway of the backend:

  • a typed tool contract (Control Plane Tool manifest: schemas, side_effects, requires_approval, idempotent) invoked through the gateway POST /v1/tools/{name}/invoke;
  • a maker-checker workflow: Control Plane approval (POST /v1/approvals), separation of duties, quorum, approval consumed once, plus the OPA decision eai.banking_backoffice by operation type, amount, currency, rail, region, urgency, conflict of interest and authority level; the initiator never approves their own action; a sub-agent or a service identity is never an approver;
  • an Idempotency-Key header on every write of the API and an idempotency key derived from the case and its version for every call to the source system; If-Match and ETag on updates;
  • the confirmation of the source system: after submission the result stays unknown_pending_confirmation until verify_source_operation_status has re-read the source; an operation is never marked failed or success by default, and a new submission requires a new identifier and a re-read of the source.

4. Deterministic reconciliation engine​

The reconciliation engine (1:1, 1:N, N:1, groups, tolerances, currencies, date windows) is deterministic, versioned (reconciliation_rule_versions) and reproducible; it reserves matched lines transactionally, keeps every candidate and its reasons, produces control totals per currency and period, and depends on no language model. The LLM explains, summarizes and prepares; it decides no match, invents no balance and confirms no payment.

5. Observability​

Grafana, Loki and Tempo, requested by the brief, are under AGPL-3.0 and refused by ADR-0101. As for the RAG (ADR-0175), dashboards, logs and traces go through the allowed components of the catalog: Prometheus, Alertmanager, Alloy, OpenSearch and OpenSearch Dashboards, Jaeger, Opik, ClickHouse optional. The bank_ops_* metrics carry no payment or customer identifier as label; the unmatched value is exposed per currency, never aggregated across currencies. The business audit (audit_event_references) points to the chained audit of the Control Plane and survives trace sampling.

6. Memory and knowledge​

Qdrant and Docling, through the knowledge domain of the Control Plane, serve procedures, fee schedules and guides; Cognee, through the Navin Memory Provider contract (ADR-0174), is an explanatory memory of document links and never the source of truth of a financial or accounting relation or of a status. Dedicated installation per instance for banks while the separation of Cognee is only logical (ADR-0175, point 4).

7. Roles and authorizations​

The twelve logical roles (Operations Clerk, Payment Operator, Reconciliation Analyst, Suspense Analyst, Operations Supervisor, Settlement Manager, GL Controller, Credit Operations Officer, Compliance Reviewer, Operations Approver, read-only Internal Auditor, Tenant Admin) are OpenFGA relations on the additive type backoffice_instance, inherited by work_item, reconciliation_run, suspense_case, adjustment_draft, eod_checklist and document_instruction. The tenant, project and instance context always comes from the validated identity, never from the browser. Fail-closed: unavailable OpenFGA, OPA, file analysis or quotas block the protected action.

8. Replaceable connectors and standalone operation​

The Customer Operations, Compliance & Audit, KYC/AML and Credit Analysis modules are absent from the repository. UC-00 works alone: each neighbouring integration is a port (ticketing, controls_export, kyc_status, credit_decision) with a default none implementation that shows Not configured, and the banking connectors (core banking, payment hub, GL, statements, clearing) are Connector manifests of the Control Plane, read-only by default, with a capability table declared per provider. No fictitious connector; no simulated action presented as operational.

9. Template prepared, not published​

The navin-banking-backoffice-agent template is added to the navin-manager/agent-templates registry with status prepared and a descriptor validated against navin-manager/catalog/schema/service.schema.json on a temporary copy of the catalog. Nothing is copied into navin-manager/catalog before the explicit validation of the user.

10. Reuse of the RAG patterns​

FastAPI backend with asynchronous SQLAlchemy and Alembic, RLS by set_config in every transaction, durable jobs in PostgreSQL (FOR UPDATE SKIP LOCKED, outbox), runs with SSE and resume, Next.js 16 frontend with MUI and BFF (no token in the browser), OpenAPI contract published in navin-enterprise-banking-backoffice/docs/api/openapi.json, tested OPA and OpenFGA policies, service descriptor checked by a script, paired French and English documentation.

Consequences​

  • The banking controls (enriched maker-checker, source confirmation, amount matrix) live in the product and in the OPA package, without changing the Control Plane domains; additive extensions remain possible.
  • One more hop through the Control Plane for every tool; latency measured by the load tests.
  • The product depends on representative banking sandboxes for its E2E tests: no tested status without them.
  • Productivity gains are only announced with a before and after measurement.

Points to validate​

  1. Replacement of Grafana, Loki and Tempo by the allowed components of the catalog (same choice as ADR-0175).
  2. Dedicated installation per instance for banks while the separation of Cognee is only logical.
  3. Default none ports for the absent neighbouring modules, without any fictitious implementation.
  4. Pre-publication only: the template stays prepared until the explicit agreement of the user.

Rejected alternatives​

  • A mirror ledger in PostgreSQL: a second set of books, contrary to the brief.
  • Matches proposed by the LLM: not reproducible, not auditable.
  • Direct execution of banking actions from the tool, without Action Gateway: no source confirmation and no protection against double execution.
  • Grafana, Loki and Tempo: AGPL-3.0, refused by ADR-0101.
  • Immediate publication in the Manager catalog.

Delivery plan​

Fourteen batches tracked on the project board, in the order of section 23 of the brief: audit and ADR; v1 contracts; payment schemas and source connectors; ingestion, events, workflows and permissions; 1:1 reconciliation engine and totals; N:M, tolerances, ambiguities and versioning; suspense, exceptions and repairs; controlled source actions and maker-checker; documents and extraction; EOD control; operational interfaces; RAG, copilot and reports; tests of the invariants, of double execution and of security; observability, HA and Navin Manager packaging.