kdrucshi/bil-loan-approver

Purpose and entry points

Loan Compliance Review Agent evaluates a large secured-loan portfolio against deterministic compliance rules, persists per-run results, and routes failures through auditable human review. Runtime entry points are FastAPI in backend/app/main.py, batch evaluation in backend/pipeline/run_evaluation.py, and the React UI in frontend/src/main.jsx / frontend/src/App.jsx.

API and presentation boundary

backend/app/main.py exposes run triggering, dashboard/history/query APIs, review decisions, report downloads, and assistant endpoints. It keeps request orchestration separate from SQL reads in backend/app/queries.py, reporting in backend/app/reports.py, and remediation writes in backend/agent/review_actions.py. The Vite frontend presents portfolio views and the review workflow; the focused review UI is frontend/src/JourneyReview.jsx.

Evaluation pipeline

A run streams source loans rather than loading the portfolio at once. backend/pipeline/run_evaluation.py orchestrates reference-data loading, loan input construction, batches of 500, OPA evaluation, and incremental SQLite persistence. backend/pipeline/parse_pdf.py turns the company reference PDF into a cached company/asset representation; backend/pipeline/compute_inputs.py derives policy-ready fields using Decimal arithmetic.

Deterministic policy boundary

OPA exclusively produces rule verdicts: minimum EUR loan value, HQ-country currency matching, and collateral coverage. Policies are composed in backend/policies/main.rego, with individual rules in backend/policies/rule1_min_value.rego, backend/policies/rule2_currency.rego, and backend/policies/rule3_coverage.rego. backend/pipeline/opa_client.py is the boundary to OPA’s REST endpoint; policy code does comparisons only and does not retrieve data or invoke models.

Reference and FX enrichment

The pipeline resolves expected currency from a static mapping in backend/pipeline/country_currency.py and obtains FX data via backend/pipeline/fx.py, with live-provider/fallback caching behavior. Parsed PDF companies/assets and CSV loans form the authoritative domain inputs; absent source facts must not be invented.

Persistence, reporting, and history

SQLite, managed through backend/pipeline/db.py, is the system of record for loans, reference entities, run-scoped rule results, suggestions, and audit events. Runs preserve historical result sets through run_id; only one evaluation run is intended to be active. Read models in backend/app/queries.py drive dashboards, compliance views, review queues, insights, and history. backend/app/reports.py generates PDF and streamed CSV outputs from persisted run data.

Human remediation and agent boundary

backend/agent/review_actions.py implements accept, manual, ignore, and removal decisions, records audit state, and rechecks changed cases through policy evaluation. Rules 1 and 2 receive deterministic suggestions. Rule 3 invokes the LangGraph flow in backend/agent/rule3_graph.py: exact company-asset retrieval/filtering via backend/agent/tools.py, LLM asset selection/explanation, then a human-review gate before application. Azure OpenAI is isolated behind backend/agent/llm_client.py; it assists only where collateral substitution requires judgment.

Runtime infrastructure

FastAPI/Python runs on port 8000; React/Vite runs on 5173 and proxies API calls. OPA runs as a Docker/Podman container on 8181, configured by docker-compose.yml with backend/policies mounted. External dependencies are Azure OpenAI and FX-rate providers; SQLite is local storage.