database.md

Fin-Trust - Database Documentation

This document describes the database design, schemas, and relationships implemented in MongoDB via Mongoose.

---

📊 Database ER Diagram

The system uses standard relational referencing between collections inside MongoDB.

erDiagram
    USER ||--o| BORROWER : "one-to-one (has borrower profile)"
    USER ||--o| LENDER : "one-to-one (has lender profile)"
    BORROWER ||--o{ MATCH : "one-to-many"
    LENDER ||--o{ MATCH : "one-to-many"

    USER {
        ObjectId _id
        string name
        string email
        string password
        string role
        boolean isActive
        boolean isVerified
        string otpHash
        date otpExpiry
        date lastOtpSentAt
    }

    BORROWER {
        ObjectId _id
        ObjectId user
        string fullName
        number age
        string occupation
        number income
        number loanAmount
        string purpose
        number repaymentDuration
        string address
        string location
        number latitude
        number longitude
        string phone
        number trustScore
        string riskLevel
        string status
    }

    LENDER {
        ObjectId _id
        ObjectId user
        string fullName
        number maxLendingAmount
        number minLendingAmount
        string preferredLocation
        number latitude
        number longitude
        string phone
        number minTrustScore
        number interestRate
        number preferredLoanDuration
        boolean isActive
    }

    MATCH {
        ObjectId _id
        ObjectId borrower
        ObjectId lender
        number matchScore
        string status
        boolean lenderAgreedToDisclaimer
    }

Loading

---

📁 Collections Schema Overview

1. users Collection

Stores basic account profile details, credentials, and verification keys.

Field	Type	Required	Description
_id	ObjectId	Yes	Unique user identifier.
name	String	Yes	User's registration name.
email	String	Yes	Unique lowercase email address.
password	String	Yes	Hashed security password.
role	String	Yes	One of borrower, lender, or admin. Default is borrower.
isActive	Boolean	Yes	Controls status access. Defaults to true.
isVerified	Boolean	Yes	Set to true after verifying OTP. Defaults to false.
otpHash	String	No	Hash of the generated verification code.
otpExpiry	Date	No	Expiration timestamp for the active verification OTP.
lastOtpSentAt	Date	No	Timestamp of the last OTP email request (for cooldown).

2. borrowers Collection

Contains financial profile data, auto-resolved coordinates, KYC validation metrics, and scoring ratings.

Field	Type	Description
user	ObjectId (Ref: User)	Reference linking back to the User account.
fullName	String	User's full legal name.
age	Number	Verified age of the borrower (min 18).
income	Number	Monthly net income value.
loanAmount	Number	Requested borrowing amount.
repaymentDuration	Number	Desired repayment cycle in months.
location	String	Town/city name.
latitude	Number	Precise geocoded latitude coordinate.
longitude	Number	Precise geocoded longitude coordinate.
trustScore	Number	Calculated trust score (0–100).
riskLevel	String	Computed category: Low Risk, Medium Risk, High Risk.
status	String	Current state: pending, matched, accepted, rejected.

3. lenders Collection

Configures matching criteria, preferences, and loan requirements.

Field	Type	Description
user	ObjectId (Ref: User)	Reference linking back to the User account.
fullName	String	User's full legal name.
maxLendingAmount	Number	Maximum cap on loan investments.
minLendingAmount	Number	Minimum cap on loan investments.
preferredLocation	String	City name for location matching.
minTrustScore	Number	Threshold for acceptable borrower risk (0-100).
interestRate	Number	Yield rates in percentages.
preferredLoanDuration	Number	Desired tenure in months.

4. matches Collection

Connects borrowers and lenders, storing percentage scores and accept/reject statuses.

Field	Type	Description
borrower	ObjectId (Ref: Borrower)	Reference to matching Borrower profile.
lender	ObjectId (Ref: Lender)	Reference to matching Lender profile.
matchScore	Number	Percentage match rank based on filters.
breakdown	Object	Individual weight percentages (location, amount, trust, duration).
status	String	Match state: suggested, accepted, rejected.
lenderAgreedToDisclaimer	Boolean	Flag indicating compliance agreement check.