# aryannehe/loanr architecture

> Architecture diagram of the GitHub repository aryannehe/loanr, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aryannehe/loanr
- Repository: https://github.com/aryannehe/loanr

## Overview

PLRS is a personalized loan recommendation product: the user supplies a financial profile, optional portfolio, loan requirement and risk appetite, then receives a ranked decision or an explicit no-suitable-loan outcome with alternatives, risk, trace and explanation. Its central workflow runs deterministic financial and portfolio analysis, eligibility and candidate generation before risk and suitability scoring; deterministic validation and guardrails then accept or block ranked options. The React UI submits requests to FastAPI and presents results. The README documents the major stages and capabilities; some implementation links, notably the India rates service, are not established by the excerpts and are left unverified.

Main entry points: [`app/core/recommendation.py`](https://github.com/aryannehe/loanr/blob/main/app/core/recommendation.py) (Recommendation orchestration), [`app/api/routes.py`](https://github.com/aryannehe/loanr/blob/main/app/api/routes.py) (FastAPI routes), [`frontend/src/App.tsx`](https://github.com/aryannehe/loanr/blob/main/frontend/src/App.tsx) (Loan workflow UI), [`frontend/src/api/client.ts`](https://github.com/aryannehe/loanr/blob/main/frontend/src/api/client.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["User interface"]
  node_app_ui["Loan workflow UI<br/>[App.tsx]"]
  node_profile_form["Profile entry<br/>[ProfileForm.tsx]"]
  node_portfolio_form["Portfolio entry<br/>[PortfolioForm.tsx]"]
  node_requirement_form["Loan requirement"]
  node_api_client["API client<br/>[client.ts]"]
  node_results_ui["Decision results<br/>[ResultsScreen.tsx]"]
  node_rates_ui["Bank rates panel<br/>[IndiaBankRates.tsx]"]
end

subgraph group_api["API surface"]
  node_fastapi["FastAPI routes<br/>[routes.py]"]
  node_catalogue["Loan catalogue<br/>[catalogue.py]"]
  node_india_rates["India rates service"]
end

subgraph group_domain["Decision pipeline"]
  node_financial["Financial analysis<br/>[financial.py]"]
  node_portfolio["Portfolio analysis<br/>[portfolio.py]"]
  node_eligibility["Eligibility rules<br/>[eligibility.py]"]
  node_candidates["Candidate generation<br/>[candidates.py]"]
  node_finance_math["Finance calculations<br/>[finance_math.py]"]
  node_orchestrator["Recommendation orchestration<br/>[recommendation.py]"]
  node_validation["Candidate validation<br/>[validation.py]"]
  node_guardrails["Safety guardrails<br/>[guardrails.py]"]
end

subgraph group_models["Scoring and explanation"]
  node_risk_model["Risk prediction<br/>[risk.py]"]
  node_features["Feature assembly<br/>[features.py]"]
  node_recommender["Suitability ranking<br/>[recommender.py]"]
  node_xai["Feature contributions<br/>[xai.py]"]
  node_explanation["Natural-language explanation<br/>[llm.py]"]
end

subgraph group_state["Personalization and state"]
  node_history_context["Personalization context<br/>[context.py]"]
  node_history_store[("Pseudonymous history<br/>[store.py]")]
  node_session_log[("Recommendation logging<br/>[mongo_log.py]")]
end

node_customer(("Loan applicant"))

node_customer -->|"enters details"| node_app_ui
node_app_ui -->|"collects profile"| node_profile_form
node_app_ui -->|"collects portfolio"| node_portfolio_form
node_app_ui -->|"collects requirement"| node_requirement_form
node_app_ui -->|"submits request"| node_api_client
node_api_client -->|"sends request"| node_fastapi
node_fastapi -->|"requests decision"| node_orchestrator
node_fastapi -->|"analyzes finances"| node_financial
node_fastapi -->|"analyzes portfolio"| node_portfolio
node_fastapi -->|"loads products"| node_catalogue
node_orchestrator -->|"derives metrics"| node_financial
node_orchestrator -->|"derives metrics"| node_portfolio
node_orchestrator -->|"loads preferences"| node_history_context
node_history_context -->|"reads history"| node_history_store
node_orchestrator -->|"checks products"| node_eligibility
node_orchestrator -->|"generates options"| node_candidates
node_candidates -->|"computes EMI"| node_finance_math
node_orchestrator -->|"predicts risk"| node_risk_model
node_orchestrator -->|"ranks candidates"| node_recommender
node_recommender -->|"assembles features"| node_features
node_orchestrator -->|"checks ranked options"| node_validation
node_orchestrator -->|"enforces caps"| node_guardrails
node_orchestrator -->|"requests contributions"| node_xai
node_orchestrator -->|"requests explanation"| node_explanation
node_explanation -->|"explains decision"| node_customer
node_orchestrator -->|"returns decision"| node_fastapi
node_fastapi -->|"logs session"| node_session_log
node_fastapi -->|"returns result"| node_results_ui
node_app_ui -->|"shows outcome"| node_results_ui
node_app_ui -->|"displays rates"| node_rates_ui
node_fastapi -.->|"serves rate data"| node_india_rates

click node_app_ui "https://github.com/aryannehe/loanr/blob/main/frontend/src/App.tsx"
click node_profile_form "https://github.com/aryannehe/loanr/blob/main/frontend/src/screens/ProfileForm.tsx"
click node_portfolio_form "https://github.com/aryannehe/loanr/blob/main/frontend/src/screens/PortfolioForm.tsx"
click node_requirement_form "https://github.com/aryannehe/loanr/blob/main/frontend/src/screens/RequirementForm.tsx"
click node_api_client "https://github.com/aryannehe/loanr/blob/main/frontend/src/api/client.ts"
click node_results_ui "https://github.com/aryannehe/loanr/blob/main/frontend/src/screens/ResultsScreen.tsx"
click node_rates_ui "https://github.com/aryannehe/loanr/blob/main/frontend/src/components/IndiaBankRates.tsx"
click node_fastapi "https://github.com/aryannehe/loanr/blob/main/app/api/routes.py"
click node_catalogue "https://github.com/aryannehe/loanr/blob/main/app/api/catalogue.py"
click node_financial "https://github.com/aryannehe/loanr/blob/main/app/core/financial.py"
click node_portfolio "https://github.com/aryannehe/loanr/blob/main/app/core/portfolio.py"
click node_eligibility "https://github.com/aryannehe/loanr/blob/main/app/core/eligibility.py"
click node_candidates "https://github.com/aryannehe/loanr/blob/main/app/core/candidates.py"
click node_finance_math "https://github.com/aryannehe/loanr/blob/main/app/core/finance_math.py"
click node_orchestrator "https://github.com/aryannehe/loanr/blob/main/app/core/recommendation.py"
click node_validation "https://github.com/aryannehe/loanr/blob/main/app/core/validation.py"
click node_guardrails "https://github.com/aryannehe/loanr/blob/main/app/core/guardrails.py"
click node_risk_model "https://github.com/aryannehe/loanr/blob/main/app/ml/risk.py"
click node_features "https://github.com/aryannehe/loanr/blob/main/app/ml/features.py"
click node_recommender "https://github.com/aryannehe/loanr/blob/main/app/ml/recommender.py"
click node_xai "https://github.com/aryannehe/loanr/blob/main/app/explain/xai.py"
click node_explanation "https://github.com/aryannehe/loanr/blob/main/app/explain/llm.py"
click node_history_context "https://github.com/aryannehe/loanr/blob/main/app/personalization/context.py"
click node_history_store "https://github.com/aryannehe/loanr/blob/main/app/personalization/store.py"
click node_session_log "https://github.com/aryannehe/loanr/blob/main/app/storage/mongo_log.py"
click node_india_rates "https://github.com/aryannehe/loanr/tree/main/app/india"

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_app_ui,node_profile_form,node_portfolio_form,node_requirement_form,node_api_client,node_results_ui,node_rates_ui toneBlue
class node_fastapi,node_catalogue,node_india_rates toneAmber
class node_financial,node_portfolio,node_eligibility,node_candidates,node_finance_math,node_orchestrator,node_validation,node_guardrails toneMint
class node_risk_model,node_features,node_recommender,node_xai,node_explanation toneRose
class node_history_context,node_history_store,node_session_log,node_customer toneIndigo
```

## Components

### User interface

- [Loan workflow UI](https://github.com/aryannehe/loanr/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Profile entry](https://github.com/aryannehe/loanr/blob/main/frontend/src/screens/ProfileForm.tsx): `frontend/src/screens/ProfileForm.tsx`
- [Portfolio entry](https://github.com/aryannehe/loanr/blob/main/frontend/src/screens/PortfolioForm.tsx): `frontend/src/screens/PortfolioForm.tsx`
- [Loan requirement](https://github.com/aryannehe/loanr/blob/main/frontend/src/screens/RequirementForm.tsx): `frontend/src/screens/RequirementForm.tsx`
- [API client](https://github.com/aryannehe/loanr/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`
- [Decision results](https://github.com/aryannehe/loanr/blob/main/frontend/src/screens/ResultsScreen.tsx): `frontend/src/screens/ResultsScreen.tsx`
- [Bank rates panel](https://github.com/aryannehe/loanr/blob/main/frontend/src/components/IndiaBankRates.tsx): `frontend/src/components/IndiaBankRates.tsx`

### API surface

- [FastAPI routes](https://github.com/aryannehe/loanr/blob/main/app/api/routes.py): `app/api/routes.py`
- [Loan catalogue](https://github.com/aryannehe/loanr/blob/main/app/api/catalogue.py): `app/api/catalogue.py`
- [India rates service](https://github.com/aryannehe/loanr/tree/main/app/india): `app/india`

### Decision pipeline

- [Financial analysis](https://github.com/aryannehe/loanr/blob/main/app/core/financial.py): `app/core/financial.py`
- [Portfolio analysis](https://github.com/aryannehe/loanr/blob/main/app/core/portfolio.py): `app/core/portfolio.py`
- [Eligibility rules](https://github.com/aryannehe/loanr/blob/main/app/core/eligibility.py): `app/core/eligibility.py`
- [Candidate generation](https://github.com/aryannehe/loanr/blob/main/app/core/candidates.py): `app/core/candidates.py`
- [Finance calculations](https://github.com/aryannehe/loanr/blob/main/app/core/finance_math.py): `app/core/finance_math.py`
- [Recommendation orchestration](https://github.com/aryannehe/loanr/blob/main/app/core/recommendation.py): `app/core/recommendation.py`
- [Candidate validation](https://github.com/aryannehe/loanr/blob/main/app/core/validation.py): `app/core/validation.py`
- [Safety guardrails](https://github.com/aryannehe/loanr/blob/main/app/core/guardrails.py): `app/core/guardrails.py`

### Scoring and explanation

- [Risk prediction](https://github.com/aryannehe/loanr/blob/main/app/ml/risk.py): `app/ml/risk.py`
- [Feature assembly](https://github.com/aryannehe/loanr/blob/main/app/ml/features.py): `app/ml/features.py`
- [Suitability ranking](https://github.com/aryannehe/loanr/blob/main/app/ml/recommender.py): `app/ml/recommender.py`
- [Feature contributions](https://github.com/aryannehe/loanr/blob/main/app/explain/xai.py): `app/explain/xai.py`
- [Natural-language explanation](https://github.com/aryannehe/loanr/blob/main/app/explain/llm.py): `app/explain/llm.py`

### Personalization and state

- [Personalization context](https://github.com/aryannehe/loanr/blob/main/app/personalization/context.py): `app/personalization/context.py`
- [Pseudonymous history](https://github.com/aryannehe/loanr/blob/main/app/personalization/store.py): `app/personalization/store.py`
- [Recommendation logging](https://github.com/aryannehe/loanr/blob/main/app/storage/mongo_log.py): `app/storage/mongo_log.py`

### Other components

- **Loan applicant**

## Connections

- Loan applicant → Loan workflow UI: enters details
- Loan workflow UI → Profile entry: collects profile (evidence: `frontend/src/App.tsx`)
- Loan workflow UI → Portfolio entry: collects portfolio (evidence: `frontend/src/App.tsx`)
- Loan workflow UI → Loan requirement: collects requirement (evidence: `frontend/src/App.tsx`)
- Loan workflow UI → API client: submits request (evidence: `frontend/src/App.tsx`)
- API client → FastAPI routes: sends request
- FastAPI routes → Recommendation orchestration: requests decision (evidence: `app/api/routes.py`)
- FastAPI routes → Financial analysis: analyzes finances (evidence: `app/api/routes.py`)
- FastAPI routes → Portfolio analysis: analyzes portfolio (evidence: `app/api/routes.py`)
- FastAPI routes → Loan catalogue: loads products (evidence: `app/api/catalogue.py`)
- Recommendation orchestration → Financial analysis: derives metrics (evidence: `app/core/recommendation.py`)
- Recommendation orchestration → Portfolio analysis: derives metrics (evidence: `app/core/recommendation.py`)
- Recommendation orchestration → Personalization context: loads preferences (evidence: `app/core/recommendation.py`)
- Personalization context → Pseudonymous history: reads history (evidence: `app/personalization/context.py`)
- Recommendation orchestration → Eligibility rules: checks products (evidence: `app/core/recommendation.py`)
- Recommendation orchestration → Candidate generation: generates options (evidence: `app/core/recommendation.py`)
- Candidate generation → Finance calculations: computes EMI (evidence: `app/core/candidates.py`)
- Recommendation orchestration → Risk prediction: predicts risk (evidence: `app/core/recommendation.py`)
- Recommendation orchestration → Suitability ranking: ranks candidates (evidence: `app/core/recommendation.py`)
- Suitability ranking → Feature assembly: assembles features (evidence: `app/ml/recommender.py`)
- Recommendation orchestration → Candidate validation: checks ranked options (evidence: `app/core/recommendation.py`)
- Recommendation orchestration → Safety guardrails: enforces caps (evidence: `app/core/recommendation.py`)
- Recommendation orchestration → Feature contributions: requests contributions
- Recommendation orchestration → Natural-language explanation: requests explanation
- Natural-language explanation → Loan applicant: explains decision
- Recommendation orchestration → FastAPI routes: returns decision (evidence: `app/api/routes.py`)
- FastAPI routes → Recommendation logging: logs session (evidence: `app/api/routes.py`)
- FastAPI routes → Decision results: returns result
- Loan workflow UI → Decision results: shows outcome (evidence: `frontend/src/App.tsx`)
- Loan workflow UI → Bank rates panel: displays rates (evidence: `frontend/src/App.tsx`)
- FastAPI routes → India rates service: serves rate data (evidence: `app/api/routes.py`)
