LoanLife Edge

A secure desktop application that transforms each loan into a Digital Twin, continuously monitored by AI, governed by smart contracts, and logged on a permissioned blockchain.

TechBridle Team

Tech Stack

What This Is

A loan monitoring system that predicts covenant breaches and ESG failures 30-90 days ahead. Banks get early warnings before loans go bad. It's like a health monitor for loans, powered by AI and blockchain.

Team (TechBridle Team)

Nicolette - Backend & AI Integration Lead (APIs, AI, digital twin logic) ✅ Complete
Lunga - Blockchain & Backend Engineer (Blockchain, smart contracts) ✅ Complete
Sharon - Frontend Engineer – Desktop & UX (Electron, navigation, UX) ✅ Complete

Repository Structure

LoanLife_Edge/
├── README.md
├── .gitignore
├── package.json          # Frontend dependencies (Next.js + Electron)
├── app/                  # Next.js App Router pages
│   ├── page.tsx          # Portfolio dashboard
│   ├── digital-twins/    # Digital twin monitor page
│   ├── risk-analytics/   # Risk analytics page
│   ├── audit-log/        # Audit log page
│   └── ...
├── components/           # React components
│   ├── portfolio-dashboard.tsx
│   ├── loan-health-grid.tsx
│   ├── audit-log-panel.tsx
│   ├── esg-compliance.tsx
│   └── ui/              # shadcn/ui components
├── lib/                  # Frontend utilities
│   ├── api/             # API client & hooks
│   │   ├── client.ts    # HTTP client
│   │   ├── loans.ts     # Loans API
│   │   ├── predictions.ts
│   │   ├── esg.ts
│   │   └── audit.ts
│   └── utils.ts
├── hooks/                # React hooks
│   ├── use-loans.ts
│   ├── use-predictions.ts
│   ├── use-audit.ts
│   └── use-esg.ts
├── services/
│   ├── api/              # Backend API & AI (Nicolette) ✅
│   │   ├── app/
│   │   │   ├── main.py
│   │   │   ├── api/routes/
│   │   │   └── services/
│   │   └── requirements.txt
│   └── blockchain/       # Blockchain & smart contracts (Lunga) ✅
│       ├── contracts/    # Solidity smart contracts
│       └── api/          # Blockchain API bridge (Node.js)
├── shared/
│   └── models/           # Shared data models (Python)
├── scripts/
│   ├── seed-data/        # Seed data scripts
│   ├── start-all.sh      # Start all services (Linux/Mac)
│   ├── start-all.ps1     # Start all services (Windows)
│   └── test_api.py       # API testing script
├── electron/             # Electron main process
└── docs/
    ├── architecture.md
    ├── api-spec.md
    ├── srs.md
    ├── frontend-backend-integration.md  # Integration guide
    └── ui-ux-review.md                  # UI/UX review & improvements

Getting Started

Running Locally

Quick Start (Windows):

.\scripts\start-all.ps1

Quick Start (Mac/Linux):

chmod +x scripts/start-all.sh
./scripts/start-all.sh

This starts:

Blockchain node (port 8545)
Blockchain API bridge (port 3001)
Backend API (port 8000)

Then start the frontend:

npm install
npm run dev

Open http://localhost:3000

Note: For local development, set SEED_DATA=true in your backend environment to load demo data, or upload loan documents via the API.

See Quick Start Guide for detailed steps.

Deploying to Free Platforms

Backend → Render:

Go to render.com, sign up with GitHub
New Web Service → Connect repo
Root Directory: services/api
Build: pip install -r requirements.txt
Start: uvicorn app.main:app --host 0.0.0.0 --port $PORT
Add env vars: SEED_DATA=true (to populate demo data), BLOCKCHAIN_ENABLED=false
Restart service after setting env vars

Frontend → Vercel:

Go to vercel.com, sign up with GitHub
New Project → Import repo
Add env var: NEXT_PUBLIC_API_URL=https://your-backend.onrender.com
Deploy (auto-deploys on push to main)

See Quick Start Guide for complete deployment steps.

What We Built

Backend:

Document upload (PDF/DOCX) with automatic covenant and ESG extraction
Digital twin system tracks each loan's health in real-time
AI predictions forecast covenant breaches 30/60/90 days ahead
ESG scoring across environmental, social, and governance metrics
Blockchain logging creates immutable audit trails
Smart contracts enforce covenant rules automatically

Frontend:

Electron desktop app and web version (Next.js)
Portfolio dashboard displays all loans with health scores
Predictive risk timeline visualizes upcoming events
ESG compliance tracker aggregates scores across loans
Audit log shows blockchain transaction hashes for verification
Auto-refresh keeps data current without manual reloads
Light/dark theme switching
Responsive design works on desktop, tablet, and mobile

Status

Development Complete ✅

All core features are implemented and working. The application is deployed and functional:

Nicolette (Backend): API endpoints operational, document parsing extracts covenants and ESG data, AI predictions generate 30/60/90-day forecasts, blockchain integration handles on-chain logging.

Lunga (Blockchain): Smart contracts deployed and functional, API bridge connects backend to blockchain, full integration complete. Blockchain transaction hashes visible in audit logs.

Sharon (Frontend): Next.js web app and Electron desktop version both working, all components fetch real data from APIs, real-time updates refresh automatically, responsive design works across devices, light/dark theme switching implemented.

Deployment:

Frontend: Deployed on Vercel (https://loan-life-edge.vercel.app/)
Backend: Deployed on Render (https://loanlife-edge.onrender.com/)
Seed data: Populated and displaying correctly
All features: Tested and working

Ready for hackathon demo.

API Endpoints

Loans

POST /api/v1/loans/upload - Upload loan document
GET /api/v1/loans - List all loans
GET /api/v1/loans/{loan_id} - Get loan details
GET /api/v1/loans/{loan_id}/state - Get digital twin state
POST /api/v1/loans/{loan_id}/covenant-check - Record covenant check

Predictions

GET /api/v1/predictions/{loan_id} - Get risk predictions (30/60/90 days)
GET /api/v1/predictions/{loan_id}/covenant/{covenant_id} - Covenant-specific prediction
GET /api/v1/predictions/{loan_id}/explainability - Get prediction explanation

ESG

GET /api/v1/esg/{loan_id}/score - Get ESG score
GET /api/v1/esg/{loan_id}/compliance - Get compliance summary
GET /api/v1/esg/{loan_id}/breach-risk - Predict ESG breach risk
POST /api/v1/esg/{loan_id}/compliance-check - Record ESG compliance check

Audit

GET /api/v1/audit - Get audit logs (with filters)
GET /api/v1/audit/{loan_id}/summary - Get audit summary for loan

Blockchain API Bridge

POST /api/v1/covenants/register - Register covenant on blockchain
POST /api/v1/audit/log - Log audit entry to blockchain
POST /api/v1/esg/record - Record ESG score on blockchain
POST /api/v1/governance/detect-breach - Detect breach on blockchain
GET /health - Blockchain service health check

Environment Variables

Backend API

SEED_DATA - Set to "true" to load demo data on startup
BLOCKCHAIN_ENABLED - Set to "true" to enable blockchain integration
BLOCKCHAIN_API_URL - Blockchain API bridge URL (default: http://localhost:3001)

Frontend

Create a .env.local file in the root directory:

NEXT_PUBLIC_API_URL=http://localhost:8000

The frontend defaults to http://localhost:8000 if not specified.

Blockchain

BLOCKCHAIN_RPC_URL - Hardhat node RPC URL (default: http://127.0.0.1:8545)
BLOCKCHAIN_API_PORT - Blockchain API bridge port (default: 3001)

Testing the Integration

Backend & Blockchain

Start all services using the startup scripts
Check health endpoints:
- Backend: http://localhost:8000/health
- Blockchain: http://localhost:3001/health
Upload a loan document via /api/v1/loans/upload
Check blockchain integration:
- Covenant registration happens automatically
- Audit logs include blockchain transaction hashes
- ESG scores are recorded on-chain
View predictions via /api/v1/predictions/{loan_id}
Check audit logs via /api/v1/audit

Frontend Application

Start backend services (API + Blockchain) - see above
Start frontend:
```
npm install
npm run dev
```
Open the application:
- Web: http://localhost:3000
- Or Electron: npm run electron:dev
Verify integration:
- Portfolio dashboard loads real loan data
- Loan health scores display correctly
- Audit logs show blockchain transaction hashes
- ESG compliance aggregates across all loans
- Risk timeline displays predictions

API Testing Script

# Run the test script
cd scripts
python test_api.py

This will test all major API endpoints and verify the integration.

Architecture

┌─────────────────────────────────────────────────────────────┐
│        Electron Desktop App / Web App (Frontend)            │
│                   Next.js + React + Electron                │
│                         (Sharon) ✅                          │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │   React      │  │   API Client │  │   Hooks      │     │
│  │  Components  │  │   (lib/api)  │  │  (hooks/)    │     │
│  └──────────────┘  └──────┬───────┘  └──────────────┘     │
└────────────────────────────┼────────────────────────────────┘
                             │ HTTP/REST API
┌────────────────────────────▼────────────────────────────────┐
│              Backend API (FastAPI)                          │
│                    (Nicolette) ✅                           │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │  Ingestion   │  │ Digital Twin │  │ AI Prediction│     │
│  │   Service    │  │   Service    │  │   Service    │     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │ ESG Service  │  │Audit Service │  │ Blockchain   │     │
│  │              │  │              │  │   Client     │     │
│  └──────────────┘  └──────────────┘  └──────┬───────┘     │
└──────────────────────────────────────────────┼─────────────┘
                                                │ HTTP
┌───────────────────────────────────────────────▼─────────────┐
│         Blockchain API Bridge (Node.js/Express)            │
│                    (Lunga) ✅                               │
└────────────────────┬────────────────────────────────────────┘
                     │ Web3.js
┌────────────────────▼────────────────────────────────────────┐
│         Hardhat Local Blockchain Node                      │
│         (Permissioned Blockchain Mock)                     │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐    │
│  │  Covenant    │  │ Governance   │  │ Audit        │    │
│  │  Registry    │  │   Rules      │  │ Ledger       │    │
│  └──────────────┘  └──────────────┘  └──────────────┘    │
└────────────────────────────────────────────────────────────┘

Key Integration Points

Frontend ↔ Backend: RESTful API with TypeScript types
Backend ↔ Blockchain: HTTP API bridge (Node.js/Express)
Data Flow: Frontend hooks → API client → Backend → Blockchain
Real-time Updates: Auto-refresh intervals (audit: 10s, predictions: 60s, states: 30s)

Documentation

Setup & Integration

Backend API Documentation
Frontend-Backend Integration Guide - Complete integration documentation
UI/UX Review & Improvements - Principal engineer review with actionable improvements

Specifications

Quick Links

API Client: lib/api/ - Centralized API client with TypeScript types
React Hooks: hooks/ - Custom hooks for data fetching (useLoans, usePredictions, useAudit, useESG)
Components: components/ - Reusable UI components

Current Limitations

Since this is a hackathon demo, there are some shortcuts we took:

Data is in-memory (restarts clear it). Production needs a real database.
AI predictions are simulated. Real deployment would need trained ML models.
Blockchain runs on local Hardhat node. Production would use a permissioned network.
No authentication yet. Production needs proper security.
Mobile responsiveness is basic (we prioritized desktop).

Production roadmap:

Replace in-memory storage with PostgreSQL
Add authentication and authorization
Train and deploy real ML models
Connect to a production blockchain network
Enhance mobile responsiveness
Add unit and integration tests
Set up monitoring and logging

For the hackathon demo, everything works as expected.

License

Hackathon Project - LMA EDGE Hackathon 2025

Name		Name	Last commit message	Last commit date
Latest commit History 93 Commits
app		app
components		components
dist-electron		dist-electron
docs		docs
electron		electron
hooks		hooks
lib		lib
public		public
scripts		scripts
services		services
shared		shared
styles		styles
.gitignore		.gitignore
README.md		README.md
components.json		components.json
electron.tsconfig.json		electron.tsconfig.json
next.config.mjs		next.config.mjs
package-lock.json		package-lock.json
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
postcss.config.mjs		postcss.config.mjs
tsconfig.json		tsconfig.json
vercel.json		vercel.json

Navigation Menu

Repository files navigation

LoanLife Edge

Tech Stack

What This Is

Team (TechBridle Team)

Repository Structure

Getting Started

Running Locally

Deploying to Free Platforms

What We Built

Status

API Endpoints

Loans

Predictions

ESG

Audit

Blockchain API Bridge

Environment Variables

Backend API

Frontend

Blockchain

Testing the Integration

Backend & Blockchain

Frontend Application

API Testing Script

Architecture

Key Integration Points

Documentation

Setup & Integration

Specifications

Quick Links

Current Limitations

License

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

LoanLife Edge

Tech Stack

What This Is

Team (TechBridle Team)

Repository Structure

Getting Started

Running Locally

Deploying to Free Platforms

What We Built

Status

API Endpoints

Loans

Predictions

ESG

Audit

Blockchain API Bridge

Environment Variables

Backend API

Frontend

Blockchain

Testing the Integration

Backend & Blockchain

Frontend Application

API Testing Script

Architecture

Key Integration Points

Documentation

Setup & Integration

Specifications

Quick Links

Current Limitations

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages