codeintelli-com

Unbias — Loan Eligibility & Offer Engine Platform

A modular, scalable backend system built for lead generation, loan applications, bank offer comparison, and OTP-based authentication.

This backend powers the Unbias Loan Platform, enabling users to submit loan requirements, evaluate eligibility, generate multi-bank offers, compare offers, and submit final loan applications. It includes admin tools for lead management, offer regeneration, and agent assignment.

📌 Table of Contents

• Overview
• Features
• Tech Stack
• Folder Structure
• Environment Variables
• API Route Summary
• Request Validation
• Services Overview
• Setup & Installation
• Running the Project
• Build & Deployment
• Coding Conventions
• Common Commands
• Future Enhancements

🧭 Overview

Unbias is an end-to-end backend system designed for:

• Lead onboarding through dynamic multi-step forms
• Eligibility calculation (LTV, EMI, FOIR & more)
• OTP verification for secure login & user identity
• Loan application creation
• Bank offer generation using a custom Offer Engine
• Offer comparison with score ranking
• Admin panel backend for status updates & agent assignment

The application is designed for scalability, modularity, and fast iteration.

🚀 Features

✔ User & OTP Authentication

Secure OTP-based verification using hashed OTPs, expiries, attempt limits, and rate protection.

✔ Lead Management

Multi-step lead registration with:

• Personal profile
• Property information
• Income sources (multiple)
• EMI liabilities (unlimited)
• Co-applicant details
• Eligibility scoring

✔ Loan Application

Auto-creation from leads, upload user documents, update application status.

✔ Offer Engine

Generates offers from bank products with configurable logic:

• Base interest rate
• Tenure eligibility
• LTV impact
• FOIR logic
• Pre-approved flags
• Match score ranking

✔ Offer Comparison

Tabular comparison of multiple offers, normalized scoring.

✔ Admin Panel Support

• Lead listing
• Status change
• Assign to agent
• Offer regeneration

🧰 Tech Stack

Layer	Technology
Language	Node.js (ES Modules)
Framework	Express.js
Database	MongoDB + Mongoose
Auth	OTP (Crypto), JWT (User Auth)
Storage	AWS S3 / Local Storage (configurable)
Logging	Winston / Morgan
Validation	Joi
API Docs	Swagger-ready (Loader included)

📁 Folder Structure

Src/
├── Controller/                # All controllers
├── Models/                    # Mongoose models
├── Services/                  # Business logic (OTP, OfferEngine, EMI)
├── Middleware/                # Auth, validation, uploads, errors
├── Routes/                    # API routes grouped by module
├── Validations/               # Joi validation schemas
├── Utils/                     # Helpers, Custom handlers, Logger, LTV/EMI helpers
├── Loaders/                   # Server, DB, Morgan, Swagger initialization
├── Templates/                 # Email templates (OTP, Offer summary)
├── Uploads/                   # Uploaded files if local storage
Config/                        # Environment and global configurations
main.js                        # App bootstrap
package.json
config.env

🔐 Environment Variables

Create a config.env file in root:

PORT=5000
NODE_ENV=development

# Database
MONGO_URI=mongodb://localhost:27017/unbias

# JWT (User login system)
JWT_SECRET=your-secret
JWT_EXPIRE=2d

# OTP
OTP_EXPIRE_MINUTES=5
OTP_MAX_ATTEMPTS=5

# AWS S3 (if enabled)
AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=
AWS_REGION=
AWS_BUCKET_NAME=

# CLOUDINARY (if enabled)
CLOUDINARY_NAME=
CLOUDINARY_API_KEY=
CLOUDINARY_API_SECRET=

# SMTP / Email
SMTP_HOST=
SMTP_PORT=
SMTP_USER=
SMTP_PASS=

🌐 API Route Summary

Auth

POST /auth/login
POST /auth/register   (optional)

OTP

POST /otp/send
POST /otp/verify

Lead

POST   /lead/create
PATCH  /lead/:id/update-step
GET    /lead/:id
PATCH  /lead/:id/add-income
PATCH  /lead/:id/add-emi
PATCH  /lead/:id/add-co-applicant
PATCH  /lead/:id/update-property
PATCH  /lead/:id/update-loan-requirement
PATCH  /lead/:id/update-employment
PATCH  /lead/:id/update-eligibility
POST   /lead/:id/submit

Loan Application

POST   /application/create
GET    /application/:id
PATCH  /application/:id/update
POST   /application/:id/upload-document
POST   /application/generate-offers
PATCH  /application/:id/select-offer

Offers

GET  /offers/list
POST /offers/compare
POST /offers/regenerate   (admin)

Banks

GET /bank/list

Admin

GET   /admin/leads
PATCH /admin/lead/:id/status
PATCH /admin/lead/:id/assign

🧩 Request Validation

Every route uses Joi validation via the custom middleware:

ValidateRequest(schema, "body" | "query" | "params");

Validation files:

• LeadValidation.js
• LoanApplicationValidation.js
• OtpValidation.js
• OfferValidation.js
• AdminValidation.js

⚙️ Services Overview

OTPService

• Generates hashed OTP
• Stores expiry, attempts, locked flag
• Verifies user OTP

OfferEngine

• Loads bank products
• Applies eligibility rules
• Calculates interest, EMI, match_score
• Creates Offer documents

EmiService

• Standard EMI formula
• Amortization schedule support

S3Service / FileUploadService

• Handles document uploads
• Supports AWS S3 / Cloudinary / Local FS

🛠 Setup & Installation

1️⃣ Clone repo

git clone https://github.com/<your-org>/unbias-backend.git
cd unbias-backend

2️⃣ Install dependencies

yarn install
# or
npm install

3️⃣ Configure environment

Copy .env.example (if present) or create config.env.

▶️ Running the Server

Development mode:

yarn dev

Production mode:

yarn build
yarn start

🚀 Build & Deployment

Recommended deployment stack:

• Docker container with Node.js 20
• MongoDB Atlas
• AWS ECS / Elastic Beanstalk / Railway
• S3 for file storage
• CloudFront for CDN
• PM2 if deploying on VM

📏 Coding Conventions

✔ ES modules (import/export)

✔ Controllers contain only request handling logic

✔ Services contain business logic

✔ Models follow snake_case fields with created_at, updated_at, deleted_at, is_active

✔ Validation required for every endpoint

✔ Success responses formatted with SuccessHandler

✔ Error responses handled by CustomErrorHandler

✔ No worker suffix in controller names

🔧 Common Commands

# Start dev server
yarn dev

# Build
yarn build

# Format code
yarn format