# lositha/loanlens architecture

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

- Interactive diagram: https://gitdiagram.com/lositha/loanlens
- Repository: https://github.com/lositha/loanlens

## Overview

LoanLens is a Streamlit loan-offer analyzer. A user enters or pastes loan terms; the app extracts fields, computes payment and fee-inclusive borrowing cost, then compares prepaying with investing using historical Nifty 50 data and simulations. It presents the results with charts and a plain-language explanation. The app excerpt and source index establish the main module relationships; unsampled implementation details are not expanded.

Main entry points: [`app/streamlit_app.py`](https://github.com/lositha/loanlens/blob/main/app/streamlit_app.py) (Streamlit app), [`src/loanlens/verdict.py`](https://github.com/lositha/loanlens/blob/main/src/loanlens/verdict.py) (Prepay or invest), [`src/loanlens/backtest.py`](https://github.com/lositha/loanlens/blob/main/src/loanlens/backtest.py) (Historical returns), [`src/loanlens/extractor.py`](https://github.com/lositha/loanlens/blob/main/src/loanlens/extractor.py) (AI offer reader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interface"]
  node_app["Streamlit app<br/>[streamlit_app.py]"]
end

subgraph group_loan["Loan analysis"]
  node_offer_reader["AI offer reader<br/>[extractor.py]"]
  node_rules_reader["Rule-based reader<br/>[regex_extractor.py]"]
  node_emi["EMI calculator<br/>[emi.py]"]
  node_xirr["Effective loan cost<br/>[xirr.py]"]
end

subgraph group_invest["Investment comparison"]
  node_prices["Nifty price history<br/>[nifty50.csv]"]
  node_backtest["Historical returns<br/>[backtest.py]"]
  node_montecarlo["Return simulations<br/>[montecarlo.py]"]
  node_verdict["Prepay or invest<br/>[verdict.py]"]
end

subgraph group_explain["Explanations"]
  node_explainer["Plain-language explanation<br/>[explainer.py]"]
end

node_user(("Loan seeker"))
node_ai{{"Gemini API"}}

node_user -->|"enters offer"| node_app
node_app -->|"extracts terms"| node_offer_reader
node_app -->|"reads by rules"| node_rules_reader
node_offer_reader -->|"requests extraction"| node_ai
node_app -->|"calculates payment"| node_emi
node_app -->|"calculates true cost"| node_xirr
node_xirr -->|"calculates payment"| node_emi
node_app -->|"loads prices, compares history"| node_backtest
node_backtest -->|"reads prices"| node_prices
node_app -->|"simulates returns"| node_montecarlo
node_app -->|"gets recommendation"| node_verdict
node_verdict -->|"compares historical returns"| node_backtest
node_verdict -->|"compares simulated returns"| node_montecarlo
node_app -->|"requests explanation"| node_explainer
node_explainer -->|"rewrites facts"| node_ai

click node_app "https://github.com/lositha/loanlens/blob/main/app/streamlit_app.py"
click node_offer_reader "https://github.com/lositha/loanlens/blob/main/src/loanlens/extractor.py"
click node_rules_reader "https://github.com/lositha/loanlens/blob/main/src/loanlens/regex_extractor.py"
click node_emi "https://github.com/lositha/loanlens/blob/main/src/loanlens/emi.py"
click node_xirr "https://github.com/lositha/loanlens/blob/main/src/loanlens/xirr.py"
click node_prices "https://github.com/lositha/loanlens/blob/main/data/nifty50.csv"
click node_backtest "https://github.com/lositha/loanlens/blob/main/src/loanlens/backtest.py"
click node_montecarlo "https://github.com/lositha/loanlens/blob/main/src/loanlens/montecarlo.py"
click node_verdict "https://github.com/lositha/loanlens/blob/main/src/loanlens/verdict.py"
click node_explainer "https://github.com/lositha/loanlens/blob/main/src/loanlens/explainer.py"

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 toneBlue
class node_offer_reader,node_rules_reader,node_emi,node_xirr toneAmber
class node_prices,node_backtest,node_montecarlo,node_verdict,node_ai toneMint
class node_explainer toneRose
class node_user toneIndigo
```

## Components

### User interface

- [Streamlit app](https://github.com/lositha/loanlens/blob/main/app/streamlit_app.py): `app/streamlit_app.py`

### Loan analysis

- [AI offer reader](https://github.com/lositha/loanlens/blob/main/src/loanlens/extractor.py): `src/loanlens/extractor.py`
- [Rule-based reader](https://github.com/lositha/loanlens/blob/main/src/loanlens/regex_extractor.py): `src/loanlens/regex_extractor.py`
- [EMI calculator](https://github.com/lositha/loanlens/blob/main/src/loanlens/emi.py): `src/loanlens/emi.py`
- [Effective loan cost](https://github.com/lositha/loanlens/blob/main/src/loanlens/xirr.py): `src/loanlens/xirr.py`

### Investment comparison

- [Nifty price history](https://github.com/lositha/loanlens/blob/main/data/nifty50.csv): `data/nifty50.csv`
- [Historical returns](https://github.com/lositha/loanlens/blob/main/src/loanlens/backtest.py): `src/loanlens/backtest.py`
- [Return simulations](https://github.com/lositha/loanlens/blob/main/src/loanlens/montecarlo.py): `src/loanlens/montecarlo.py`
- [Prepay or invest](https://github.com/lositha/loanlens/blob/main/src/loanlens/verdict.py): `src/loanlens/verdict.py`

### Explanations

- [Plain-language explanation](https://github.com/lositha/loanlens/blob/main/src/loanlens/explainer.py): `src/loanlens/explainer.py`

### Other components

- **Loan seeker**
- **Gemini API**

## Connections

- Loan seeker → Streamlit app: enters offer
- Streamlit app → AI offer reader: extracts terms (evidence: `app/streamlit_app.py`)
- Streamlit app → Rule-based reader: reads by rules (evidence: `app/streamlit_app.py`)
- AI offer reader → Gemini API: requests extraction (evidence: `src/loanlens/extractor.py`)
- Streamlit app → EMI calculator: calculates payment (evidence: `app/streamlit_app.py`)
- Streamlit app → Effective loan cost: calculates true cost (evidence: `app/streamlit_app.py`)
- Effective loan cost → EMI calculator: calculates payment (evidence: `src/loanlens/xirr.py`)
- Streamlit app → Historical returns: loads prices, compares history (evidence: `app/streamlit_app.py`)
- Historical returns → Nifty price history: reads prices (evidence: `src/loanlens/backtest.py`)
- Streamlit app → Return simulations: simulates returns (evidence: `app/streamlit_app.py`)
- Streamlit app → Prepay or invest: gets recommendation (evidence: `app/streamlit_app.py`)
- Prepay or invest → Historical returns: compares historical returns (evidence: `src/loanlens/verdict.py`)
- Prepay or invest → Return simulations: compares simulated returns (evidence: `src/loanlens/verdict.py`)
- Streamlit app → Plain-language explanation: requests explanation (evidence: `app/streamlit_app.py`)
- Plain-language explanation → Gemini API: rewrites facts (evidence: `src/loanlens/explainer.py`)
