# kdrucshi/bil-loan-approver architecture

> Architecture diagram of the GitHub repository kdrucshi/bil-loan-approver, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kdrucshi/bil-loan-approver
- Repository: https://github.com/kdrucshi/bil-loan-approver

## Overview

#### 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.

Main entry points: [`backend/pipeline/db.py`](https://github.com/kdrucshi/bil-loan-approver/blob/main/backend/pipeline/db.py) (Run system of record), [`backend/app/main.py`](https://github.com/kdrucshi/bil-loan-approver/blob/main/backend/app/main.py) (FastAPI server), [`backend/agent/review_actions.py`](https://github.com/kdrucshi/bil-loan-approver/blob/main/backend/agent/review_actions.py) (Review actions), [`backend/pipeline/run_evaluation.py`](https://github.com/kdrucshi/bil-loan-approver/blob/main/backend/pipeline/run_evaluation.py) (Run orchestrator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Presentation"]
  node_frontend["React review UI<br/>React/Vite<br/>[App.jsx]"]
  node_journey_review["Journey review<br/>React view<br/>[JourneyReview.jsx]"]
end

subgraph group_api["API &amp; Read Models"]
  node_api_server["FastAPI server<br/>[main.py]"]
  node_queries["Read models<br/>SQL queries<br/>[queries.py]"]
  node_reports["Report generation<br/>PDF / CSV<br/>[reports.py]"]
end

subgraph group_pipeline["Evaluation Pipeline"]
  node_run_pipeline["Run orchestrator<br/>batch pipeline<br/>[run_evaluation.py]"]
  node_reference_parser["Reference PDF parser<br/>PDF ingestion<br/>[parse_pdf.py]"]
  node_input_builder["Policy input builder<br/>Decimal derivation<br/>[compute_inputs.py]"]
  node_currency_mapping["Country currency map<br/>reference mapping"]
  node_fx_enrichment["FX enrichment<br/>rate client/cache<br/>[fx.py]"]
end

subgraph group_policy["Policy &amp; Remediation"]
  node_opa_client["OPA client<br/>REST boundary<br/>[opa_client.py]"]
  node_opa_policies["Compliance policies<br/>Rego rules<br/>[main.rego]"]
  node_review_actions["Review actions<br/>remediation service<br/>[review_actions.py]"]
  node_rule3_graph["Collateral review flow<br/>LangGraph<br/>[rule3_graph.py]"]
  node_asset_tools["Asset retrieval tools<br/>exact retrieval<br/>[tools.py]"]
  node_llm_client["Azure OpenAI boundary<br/>LLM client<br/>[llm_client.py]"]
end

subgraph group_runtime["Storage &amp; External Services"]
  node_sqlite[("Run system of record<br/>SQLite<br/>[db.py]")]
  node_opa_runtime{{"OPA runtime<br/>container service<br/>[docker-compose.yml]"}}
  node_source_data["Loan CSV &amp; reference PDF<br/>authoritative inputs"]
  node_fx_providers(("FX-rate providers<br/>external service"))
  node_azure_openai(("Azure OpenAI<br/>external LLM"))
end

node_frontend -->|"renders"| node_journey_review
node_frontend -->|"API requests"| node_api_server
node_api_server -->|"triggers run"| node_run_pipeline
node_api_server -->|"reads views"| node_queries
node_api_server -->|"downloads"| node_reports
node_api_server -->|"submits decisions"| node_review_actions
node_queries -->|"run-scoped reads"| node_sqlite
node_reports -->|"persisted data"| node_sqlite
node_source_data -->|"reference PDF"| node_reference_parser
node_source_data -->|"loan stream"| node_run_pipeline
node_reference_parser -->|"companies and assets"| node_sqlite
node_run_pipeline -->|"loan batches"| node_input_builder
node_currency_mapping -->|"expected currency"| node_input_builder
node_fx_enrichment -->|"FX rates"| node_input_builder
node_fx_providers -->|"live rates"| node_fx_enrichment
node_input_builder -->|"policy inputs"| node_opa_client
node_opa_client -->|"REST evaluation"| node_opa_runtime
node_opa_runtime -->|"mounted policies"| node_opa_policies
node_run_pipeline -->|"incremental results"| node_sqlite
node_review_actions -->|"audit and updates"| node_sqlite
node_review_actions -->|"rechecks cases"| node_opa_client
node_review_actions -->|"rule-3 cases"| node_rule3_graph
node_rule3_graph -->|"retrieves candidates"| node_asset_tools
node_asset_tools -->|"exact asset facts"| node_sqlite
node_rule3_graph -->|"selection and explanation"| node_llm_client
node_llm_client -->|"LLM call"| node_azure_openai

click node_frontend "https://github.com/kdrucshi/bil-loan-approver/blob/main/frontend/src/App.jsx"
click node_journey_review "https://github.com/kdrucshi/bil-loan-approver/blob/main/frontend/src/JourneyReview.jsx"
click node_api_server "https://github.com/kdrucshi/bil-loan-approver/blob/main/backend/app/main.py"
click node_queries "https://github.com/kdrucshi/bil-loan-approver/blob/main/backend/app/queries.py"
click node_reports "https://github.com/kdrucshi/bil-loan-approver/blob/main/backend/app/reports.py"
click node_run_pipeline "https://github.com/kdrucshi/bil-loan-approver/blob/main/backend/pipeline/run_evaluation.py"
click node_reference_parser "https://github.com/kdrucshi/bil-loan-approver/blob/main/backend/pipeline/parse_pdf.py"
click node_input_builder "https://github.com/kdrucshi/bil-loan-approver/blob/main/backend/pipeline/compute_inputs.py"
click node_currency_mapping "https://github.com/kdrucshi/bil-loan-approver/blob/main/backend/pipeline/country_currency.py"
click node_fx_enrichment "https://github.com/kdrucshi/bil-loan-approver/blob/main/backend/pipeline/fx.py"
click node_opa_client "https://github.com/kdrucshi/bil-loan-approver/blob/main/backend/pipeline/opa_client.py"
click node_opa_policies "https://github.com/kdrucshi/bil-loan-approver/blob/main/backend/policies/main.rego"
click node_review_actions "https://github.com/kdrucshi/bil-loan-approver/blob/main/backend/agent/review_actions.py"
click node_rule3_graph "https://github.com/kdrucshi/bil-loan-approver/blob/main/backend/agent/rule3_graph.py"
click node_asset_tools "https://github.com/kdrucshi/bil-loan-approver/blob/main/backend/agent/tools.py"
click node_llm_client "https://github.com/kdrucshi/bil-loan-approver/blob/main/backend/agent/llm_client.py"
click node_sqlite "https://github.com/kdrucshi/bil-loan-approver/blob/main/backend/pipeline/db.py"
click node_opa_runtime "https://github.com/kdrucshi/bil-loan-approver/blob/main/docker-compose.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_frontend,node_journey_review toneBlue
class node_api_server,node_queries,node_reports toneAmber
class node_run_pipeline,node_reference_parser,node_input_builder,node_currency_mapping,node_fx_enrichment toneMint
class node_opa_client,node_opa_policies,node_review_actions,node_rule3_graph,node_asset_tools,node_llm_client toneRose
class node_sqlite,node_opa_runtime,node_source_data,node_fx_providers,node_azure_openai toneIndigo
```

## Components

### Presentation

- [React review UI](https://github.com/kdrucshi/bil-loan-approver/blob/main/frontend/src/App.jsx): React/Vite · Portfolio, history, and human-review views. · `frontend/src/App.jsx`
- [Journey review](https://github.com/kdrucshi/bil-loan-approver/blob/main/frontend/src/JourneyReview.jsx): React view · `frontend/src/JourneyReview.jsx`

### API & Read Models

- [FastAPI server](https://github.com/kdrucshi/bil-loan-approver/blob/main/backend/app/main.py): FastAPI · Exposes runs, queries, reviews, reports, and assistant endpoints. · `backend/app/main.py`
- [Read models](https://github.com/kdrucshi/bil-loan-approver/blob/main/backend/app/queries.py): SQL queries · Builds dashboard, compliance, queue, insight, and history views. · `backend/app/queries.py`
- [Report generation](https://github.com/kdrucshi/bil-loan-approver/blob/main/backend/app/reports.py): PDF / CSV · `backend/app/reports.py`

### Evaluation Pipeline

- [Run orchestrator](https://github.com/kdrucshi/bil-loan-approver/blob/main/backend/pipeline/run_evaluation.py): batch pipeline · Streams loans in 500-item batches and persists each run incrementally. · `backend/pipeline/run_evaluation.py`
- [Reference PDF parser](https://github.com/kdrucshi/bil-loan-approver/blob/main/backend/pipeline/parse_pdf.py): PDF ingestion · Caches company and asset reference facts. · `backend/pipeline/parse_pdf.py`
- [Policy input builder](https://github.com/kdrucshi/bil-loan-approver/blob/main/backend/pipeline/compute_inputs.py): Decimal derivation · `backend/pipeline/compute_inputs.py`
- [Country currency map](https://github.com/kdrucshi/bil-loan-approver/blob/main/backend/pipeline/country_currency.py): reference mapping · `backend/pipeline/country_currency.py`
- [FX enrichment](https://github.com/kdrucshi/bil-loan-approver/blob/main/backend/pipeline/fx.py): rate client/cache · Uses live provider data with fallback caching. · `backend/pipeline/fx.py`

### Policy & Remediation

- [OPA client](https://github.com/kdrucshi/bil-loan-approver/blob/main/backend/pipeline/opa_client.py): REST boundary · `backend/pipeline/opa_client.py`
- [Compliance policies](https://github.com/kdrucshi/bil-loan-approver/blob/main/backend/policies/main.rego): Rego rules · Deterministically checks value, currency, and collateral coverage. · `backend/policies/main.rego`
- [Review actions](https://github.com/kdrucshi/bil-loan-approver/blob/main/backend/agent/review_actions.py): remediation service · Applies accept, manual, ignore, or removal decisions and records audit state. · `backend/agent/review_actions.py`
- [Collateral review flow](https://github.com/kdrucshi/bil-loan-approver/blob/main/backend/agent/rule3_graph.py): LangGraph · Uses asset selection only for rule-3 remediation before human approval. · `backend/agent/rule3_graph.py`
- [Asset retrieval tools](https://github.com/kdrucshi/bil-loan-approver/blob/main/backend/agent/tools.py): exact retrieval · `backend/agent/tools.py`
- [Azure OpenAI boundary](https://github.com/kdrucshi/bil-loan-approver/blob/main/backend/agent/llm_client.py): LLM client · `backend/agent/llm_client.py`

### Storage & External Services

- [Run system of record](https://github.com/kdrucshi/bil-loan-approver/blob/main/backend/pipeline/db.py): SQLite · Stores loans, references, run results, suggestions, and audit events by run_id. · `backend/pipeline/db.py`
- [OPA runtime](https://github.com/kdrucshi/bil-loan-approver/blob/main/docker-compose.yml): container service · Runs policy evaluation on port 8181. · `docker-compose.yml`
- **Loan CSV & reference PDF**: authoritative inputs · Source facts are not invented when absent.
- **FX-rate providers**: external service
- **Azure OpenAI**: external LLM

## Connections

- React review UI → Journey review: renders
- React review UI → FastAPI server: API requests
- FastAPI server → Run orchestrator: triggers run
- FastAPI server → Read models: reads views
- FastAPI server → Report generation: downloads
- FastAPI server → Review actions: submits decisions
- Read models → Run system of record: run-scoped reads
- Report generation → Run system of record: persisted data
- Loan CSV & reference PDF → Reference PDF parser: reference PDF
- Loan CSV & reference PDF → Run orchestrator: loan stream
- Reference PDF parser → Run system of record: companies and assets
- Run orchestrator → Policy input builder: loan batches
- Country currency map → Policy input builder: expected currency
- FX enrichment → Policy input builder: FX rates
- FX-rate providers → FX enrichment: live rates
- Policy input builder → OPA client: policy inputs
- OPA client → OPA runtime: REST evaluation
- OPA runtime → Compliance policies: mounted policies
- Run orchestrator → Run system of record: incremental results
- Review actions → Run system of record: audit and updates
- Review actions → OPA client: rechecks cases
- Review actions → Collateral review flow: rule-3 cases
- Collateral review flow → Asset retrieval tools: retrieves candidates
- Asset retrieval tools → Run system of record: exact asset facts
- Collateral review flow → Azure OpenAI boundary: selection and explanation
- Azure OpenAI boundary → Azure OpenAI: LLM call