ADR-0187: Navin Enterprise Credit Analysis & Loan Origination Agent, a credit application on top of the Control Plane

• Status: accepted on 2026-11-04; the two open choices were settled by the client on the same day (see "Decision on the points to validate")
• Date: 2026-11-04
• Scope: new project navin-credit/ (FastAPI backend, durable jobs, screens in the shared sector-agent frontend (ADR-0180), Navin integration), additive extensions of the Control Plane (domain services/control-plane/src/eai/domains/credit, migrations V250 to V259), contracts contracts/v1/credit-*.schema.json, OpenFGA model (deploy/policies/openfga/model.fga), OPA package eai.credit (deploy/policies/opa/credit.rego), dedicated screens of the Enterprise portal, Navin Manager service descriptor prepared but not published
• Related documents: ADR-0101 (licence policy), ADR-0106 (tenancy and forced RLS), ADR-0114 (PostgreSQL source of truth), ADR-0116 (chained audit), ADR-0123 (test honesty), ADR-0174 (Mem0 and Cognee memory), ADR-0175 (RAG Agent, the model followed), audit navin-credit/docs/en/NAVIN_INTEGRATION_AUDIT.md

Context

The client asks for an end to end banking platform for credit analysis and loan origination: applications, borrowers and groups, documents, financial analysis, affordability, scoring, collateral, simulations, stress tests, decision support, credit memo, committees, contracting, controlled disbursement and facility monitoring, with an AI copilot. It is not a chatbot over documents: a real business engine is required, and no figure, no score and no decision may be produced by a language model.

The audit of 2026-11-04 shows that the Control Plane already provides the governance (knowledge with versions and pages, Cognee memory, fail-closed file scanning, object storage, approvals with separation of duties and quorum, delegations, agent runs and sub-agents, tools, connectors with a broker, Presidio, evidence, lineage, evaluation, model gateway). The whole credit business layer is missing, as are PDF, DOCX and XLSX rendering, electronic signature and any real banking connector other than simulated templates. The KYC/AML, Compliance & Audit, CO and FAI products are not available in the repository at the time of the decision.

Decision

1. Five separate engines

Engine	Responsibility	What it never does
Financial engine	verifiable calculations in decimal.Decimal: normalization, ratios, cash flows, affordability, DSCR, amortization, total cost, stress tests; versioned formulas, output of value, formula, inputs, sources and status	no floating point calculation, no calculation left to the LLM
Risk engine	runs approved and versioned models, authorized variables, explainability	no PD, LGD, EAD or expected loss without an approved model: the module is then shown "not configured"
Rule engine	eligibility, limits, delegations and exceptions, evaluated against the policy version in force	no rule the LLM can change, no hard coded threshold
AI agent	analysis, explanation, preparation of recommendations and documents from computed results and verified documents	never the source of a decision, a rate, a condition or an official figure
Human decision maker	decision under the delegation matrix and procedures, through the Control Plane approvals	no self approval

2. Absolute rules

• The LLM is never the authoritative source of a financial decision or of an official calculation. Every value shown in a memo, a table or a copilot answer comes from a recorded result of the financial engine, of the risk engine or from a verified document; the copilot answer separates facts, verified metrics, AI interpretation, limitations and human validation status.
• No disbursement is triggered by the AI. A disbursement request is prepared, checked (conditions precedent, legal, compliance, operations), authorized by distinct humans, then sent through a declared and tested banking connector with an idempotency key; only the status read back from the source system is authoritative, a submission is never shown as a transfer of funds.
• Every threshold (debt to income, DSCR, LTV, delegation amounts, tolerances) comes from the validated and versioned policies of the bank; a decision stays bound to the policy version applied. No universal value is imposed.
• Rates and fees are read from approved reference data, never invented.
• A decision, a finalized memo or a validated contract is never overwritten: every change creates a new historized version.
• No value extracted from a document enters an official calculation without human verification; an inconsistency check is never presented as fraud.

3. Two planes, one governance

Same separation as ADR-0175: the Navin Manager installs and runs the runtime (catalog service navin-credit-agent: API, jobs, web); the Control Plane carries tenants, projects, roles, models, knowledge, memory, file scanning, storage, approvals, quotas, audit, policies and traces; the credit backend carries the business layer and reaches the Control Plane only through the Python SDK enterprise_ai. It never calls Qdrant, Cognee, LiteLLM, Docling, ClamAV, YARA-X or a banking system directly: knowledge, memory, files and models go through the Control Plane domains, banking systems through the connector broker.

4. Product data

• credit schema in PostgreSQL (dedicated database, least privilege roles), asynchronous SQLAlchemy 2, asyncpg and Alembic; the Control Plane keeps its V*.sql migrations (range V250 to V259 for instance activation).
• Forced RLS on every table carried by a tenant, tenant, project and instance context set by SET LOCAL in each transaction, never kept by a pooled connection; project isolation on top of tenant isolation.
• Amounts in numeric with an explicit ISO 4217 currency; no float column for a financial value.
• Versioning through *_versions tables and status history; optimistic locking by version number.
• Durable jobs in PostgreSQL (FOR UPDATE SKIP LOCKED) with a job identity signed by the server; idempotent decisions and disbursements (unique idempotency key per tenant); Redis only for ephemeral state (cache, limits, locks, short idempotency), with TTL.
• PostgreSQL keeps the official data and decisions; Cognee enriches semantic relations and never turns an AI hypothesis into a business fact.

5. Frontend

Screens in the shared sector-agent frontend (ADR-0180), configured by the credit product manifest: Next.js 16, React 19.3, MUI 9.5, white background and black text, branding (name, logo, sidebar color, navbar color), OIDC BFF with PKCE on a confidential client of the existing Keycloak realm, server side sessions in Redis, CSRF, SSE proxy, French, English and Arabic with RTL. Development ports: 3476 (web) and 8476 (API). No screen without a real API route.

6. Document rendering and signature

• The Control Plane has no rendering engine: the credit memo and the reports are rendered by the backend (canonical JSON, PDF with ReportLab, DOCX with python-docx, XLSX with openpyxl), only from recorded results; each rendering carries the fingerprint of its version.
• Signing goes through a connector to the solution approved by the bank. Without a tested connector, no contract is shown as signed; an application approval is never shown as a qualified electronic signature.

7. Tenants and instances

• Shared or dedicated model by choice, like the RAG: one runtime per cluster serves several instances isolated by RLS, OpenFGA, object storage prefixes, Redis namespaces and the controlled Cognee mappings; one named instance of the service per credit instance when the bank requires it. The shared model is subject to the approval of the security team of each bank, in particular because the Cognee separation is only logical (ADR-0175).
• The tenant, project and instance context always comes from the validated identity and the memberships of the Control Plane, never from a browser parameter.
• Logical roles of the product (relationship manager, credit analyst, risk analyst, committee member and chair, legal, compliance, operations, auditor, administrator) carried by OpenFGA relations on additive types (borrower, application, document, score, collateral, report, committee, condition, disbursement, tool).

8. Authorization and policies

OpenFGA and OPA fail closed: a denial, or an unavailable engine, blocks the action before it runs. The OPA package eai.credit covers application access, financial data retrieval by an agent, scoring, rating override, approval, change of terms, waiver, collateral validation, disbursement preparation and authorization, and export. A sub-agent acts with its service identity and the verified context of the user, never raising its privileges; no tool runs free SQL on a banking system.

9. Fairness, borrower protection and regulation

• Data minimization and documented purpose; scoring variables inventoried and justified, proxy variable control, bias and drift assessment.
• Qualified human decision by default; generative AI neither approves nor declines a credit. An automated decision can only be enabled with a documented regulatory validation of the jurisdiction.
• Contestation, review request, data correction and human review are historized.
• Creditworthiness uses for natural persons: the classification of the system under the AI Act is to be assessed by the bank; no regulatory compliance is announced automatically. The credit bureau is only queried with a recorded legal purpose.

10. Observability

Under ADR-0101: Grafana, Loki and Tempo (AGPL-3.0) are refused and replaced by Prometheus, Alertmanager, Alloy, OpenSearch and OpenSearch Dashboards, Jaeger, ClickHouse and Opik. One trace per request (W3C traceparent), AI spans to Opik through the Control Plane adapter without full financial statements or personal data, low cardinality metrics (never an application or borrower identifier as a label), OpenLineage for calculations.

11. Memory

Cognee under the technical trial of ADR-0175 (navin-enterprise-rag/docs/en/COGNEE_TRIAL.md): standard profile of ADR-0174, pgvector vectors, embedded LadybugDB graph, access only through the Navin Memory Provider contract of the Control Plane.

12. Service template and truth of capabilities

Descriptor navin-credit-agent.yaml following the real catalog schema and a template manifest, validated on a temporary copy of the catalog; nothing is added to navin-manager/catalog/services/ without explicit approval of the client. No feature is declared done without a real test, no untested connector is declared operational, no capacity and no SLA are announced without measurement; the limits are written in navin-credit/backend/KNOWN_LIMITATIONS.md.

Consequences

• The credit business layer stays separate from the governance: Control Plane improvements benefit credit without duplication.
• The financial engine and the rule engine can be tested alone, against verified reference sets.
• Without real banking connectors or approved risk models, several modules show "not configured": this is the expected state, not a defect.
• Two migration tools: Alembic for the credit schema, V*.sql for the Control Plane.

Points to validate by the client

1. Deployment model of the instances: dedicated only, shared or dedicated by choice, or shared by default.
2. Disbursement: sent through a declared and tested core banking connector after human authorization, or never sent by the product.

Decision on the points to validate

On 2026-11-04, the client chose:

1. Shared or dedicated by choice, like the RAG, subject to the approval of the security team of each bank.
2. Sent through a declared and tested core banking connector, after human authorization by distinct persons, with an idempotency key and the result read back from the source system. Without a tested connector, the authorized request stays waiting for execution and no funds status is shown.

Rejected alternatives

• Financial calculations by the LLM or in floating point: not verifiable, uncontrolled rounding.
• Scores or PD generated by a prompt, or default values presented as regulatory.
• Universal hard coded thresholds (DSCR, LTV, debt to income).
• WeasyPrint for PDF: system libraries (Pango) to install, less suited to air-gapped installs than ReportLab.
• Direct calls to banking systems without the connector broker, or free SQL on the core banking system.
• Simulation of a banking connector or of an external score service presented as real.
• Immediate publication in the Manager catalog.

Delivery plan

Twenty four "CL" tasks tracked on the project board: audit, ADR, contracts and policies; backend and frontend; policies and products; applications and exposures; documents; financial analysis, affordability and corporate analysis; scoring; collateral and simulations; decision support and memo; committees, pricing and contracts; disbursement; monitoring; AI; connectors and fairness; screens; security, observability and lifecycle; scenarios, documentation, generators.