AI Credit Decision Engine
Relevant source files
The following files were used as context for generating this wiki page:
The AI Credit Decision Engine is a sophisticated subsystem within the DRX platform designed to automate and optimize credit limit recommendations for customers. By analyzing purchase history, repayment behavior, and real-time inventory levels, the engine provides data-driven risk scores and suggested credit caps. This system aims to balance business growth with financial safety by ensuring credit is extended only to reliable customers within sustainable parameters.
The engine operates through a multi-layered approach involving real-time feature normalization, LLM-based analysis (OpenAI), and a robust rule-based fallback system. It integrates directly with the Customer Management module and the Point of Sale (POS) system to prevent sales that exceed authorized credit limits.
Sources: README.md:14-15, lib/credit/aiEngine/limitEngine.ts:251-275, db/migrations/20250128000001_add_ai_credit_engine.sql:1-10
System Architecture
The architecture consists of a TypeScript-based logic layer, Supabase Edge Functions for risk analysis, and a PostgreSQL database for storing decisions and metrics.
Decision Workflow
The following diagram illustrates the logical flow of a credit limit computation request.
The engine prioritizes speed through Redis caching and ensures reliability by falling back to deterministic rules if the AI provider is unavailable.
Sources: lib/credit/aiEngine/limitEngine.ts:251-310, lib/utils/ai-engine.ts:35-100
Core Components and Logic
Limit Computation Engine
The primary entry point is computeAICreditLimit, which orchestrates the gathering of customer features and configuration settings. It uses a sliding window rate limiter (10 requests per hour per business) to prevent API abuse.
Key functions include:
callAILimitEngine: Constructs a prompt for the LLM containing metrics such as recency, frequency, monetary scores, and repayment ratios.applyRuleBasedFallback: Calculates a limit based on tenure and historical on-time ratios (e.g., 3x monthly average sales for established customers).clampAndValidateResult: Ensures recommendations never exceed global caps or the inventory coverage ratio.
Sources: lib/credit/aiEngine/limitEngine.ts:98-150, lib/credit/aiEngine/limitEngine.ts:182-240, lib/credit/aiEngine/limitEngine.ts:251-265
Risk Scoring and Analysis
The credit_risk Edge Function performs heavy data aggregation to calculate "aging buckets" and reliability scores. It buckets delinquent accounts into 1-7, 8-14, 15-30, and 31+ day overdue categories.
Data Model and Schema
The system utilizes specialized tables and views to track credit decisions and performance metrics.
AI Credit Decisions Table (ai_credit_decisions)
This table acts as an audit trail for every recommendation generated by the system.
| Field | Type | Description |
|---|---|---|
id | UUID | Primary key. |
decision_type | VARCHAR | 'ai_recommendation', 'manual_override', or 'auto_apply'. |
old_limit | DECIMAL | Limit before the decision. |
new_limit | DECIMAL | Limit after the decision. |
risk_score | DECIMAL | 0-100 score calculated by the engine. |
details_json | JSONB | Raw AI response and features used. |
Sources: db/migrations/20250128000001_add_ai_credit_engine.sql:12-26
Configuration Settings
Business owners can configure the engine's boundaries through the business_settings table.
| Setting | Default Value | Description |
|---|---|---|
ai_credit_engine_enabled | TRUE | Global toggle for the AI engine. |
global_max_credit_per_customer | 10000.00 | Absolute maximum credit cap. |
global_max_credit_ratio_of_inventory | 0.5 (50%) | Max credit as a percentage of total inventory value. |
default_credit_limit_for_new_customer | 1000.00 | Starting limit for customers with <30 days tenure. |
Sources: db/migrations/20250128000001_add_ai_credit_engine.sql:28-34, lib/credit/aiEngine/limitEngine.ts:37-45
Implementation Details
Feature Normalization
Before sending data to the AI, metrics are normalized. The engine considers the following "Scoring Rules":
- New Customers (<30 days): Conservative limits near the default value.
- Established Customers: Limits based on 3x monthly average sales.
- Repayment History: On-time ratios ≥ 0.95 result in low risk (20), while ratios < 0.5 result in high risk (90).
Sources: lib/credit/aiEngine/limitEngine.ts:168-180, lib/credit/aiEngine/limitEngine.ts:182-210
AI Prompt Construction
The system generates a structured prompt for OpenAI's gpt-5.1 model, requiring a strict JSON response.
// Example justification logic from fallback
function buildFallbackJustification(features, recommended_limit, current_limit) {
const parts = [];
if (features.tenure_days < 30) parts.push("New customer - conservative limit recommended");
if (features.on_time_ratio >= 0.95) parts.push("Excellent payment history");
return parts.join(". ");
}
Sources: lib/credit/aiEngine/limitEngine.ts:152-180, lib/credit/aiEngine/limitEngine.ts:233-248
Summary
The AI Credit Decision Engine provides a robust, automated framework for managing financial risk within DRX. By combining real-time data analysis with configurable business guardrails, it enables precise credit management that scales with the business's inventory and customer base. The inclusion of audit logs and rule-based fallbacks ensures that credit decisions remain transparent and operational even during external service interruptions.