Fin-Trust - Peer-to-Peer Loan AI Matching Platform

Fin-Trust is a premium, production-ready peer-to-peer (P2P) loan matching platform. It automates financial assessments, document KYC parsing, and location-based borrower-lender pairing using artificial intelligence and geolocational metrics.

---

🔗 Live Demo

• Live Link: https://fintrustinternshipproject.vercel.app/

---

📖 Table of Contents

1. Project Overview
2. Key Features
3. Technology Stack
4. System Architecture
5. Folder Structure
6. Installation & Setup
7. Environment Variables
8. Documentation Links
9. Performance Optimizations
10. Security Practices
11. Future Roadmap
12. Contribution Guidelines
13. Author Info

---

🔍 Project Overview

Fin-Trust was built to bridge the gap in decentralized loan transactions. By automating trust metric validations, the platform eliminates the high overhead costs and slow timelines of traditional credit scoring, while keeping P2P interactions transparent and secure.

How It Works:

1. Profile Setup & Location Capture: The application automatically retrieves coordinates via browser geolocation and reverse-geocodes them to a read-only city input to block user spoofing.
2. AI-Driven KYC Analysis: Uploaded credentials (Aadhaar, PAN, Bank Statements) are verified via Tesseract OCR. The parsed metadata is analyzed by the Google Gemini API to output risk rates and natural-language risk breakdowns.
3. Smart Matching: The backend computes a proximity metric using the Haversine formula and checks criteria (lending bounds, minimum trust requirements, duration alignment) to suggest highly compatible local matches.
4. Local Engagement: Users review proximity badges on their dashboards. Private names and contact links are locked and only shared after mutual match acceptance.

---

✨ Key Features

🔐 Authentication & Control

• Secure Authentication: Verification codes (OTP) sent to the user's email to verify registration.
• Stateless Tokens: Secure session validation via JWT Bearer headers.
• Role-Based Access Control: Strict routing parameters distinguishing borrower, lender, and admin portals.

📍 Local Proximity Engine

• Automated Geolocation: Fast coords resolution with Nominatim fallback checks.
• Anti-Spoofing Rules: Locked coordinates inputs to ensure location parameters cannot be modified on the page.
• Proximity Calculation: Backend computing of the exact distance in meters between matched profiles.

🛡️ Trust Analysis & AI OCR

• Document Metadata Verification: OCR scanning of PAN, Aadhaar, and Bank Statements.
• Score Generation: Automating credit scoring (0–100) using employment status, documentation uploads, and name consistency.
• Natural Language Explanations: Custom risk analysis summaries generated via the Google Gemini API.

---

🛠️ Technology Stack

Component	Technology	Description
Frontend	React 19, Vite, Tailwind CSS v4, GSAP	Client application, custom responsive layouts, micro-animations.
Backend	Node.js, Express, Multer, Mongoose	REST API framework, file uploading, database modeling.
Database	MongoDB Atlas	NoSQL document storage.
External APIs	Gemini API, OSM Nominatim	AI explanations and address resolution.
Email Client	Brevo, Resend, Nodemailer	Outbound SMTP and API email deliverability.

---

🏛️ System Architecture

Fin-Trust is structured as a client-server web app:

graph TD
  Client[Vite React Client] -->|1. Request Credentials| API[Express API Server]
  API -->|2. Query Data| DB[(MongoDB Atlas)]
  API -->|3. Evaluate Risk| Gemini[Google Gemini AI]
  API -->|4. Email OTP| Email[Brevo / Resend HTTP API]
  Client -->|Coordinates Lookup| Nominatim[OSM Nominatim Geocoder]

Loading

Detailed details are available in the Architecture Documentation.

---

📁 Folder Structure

fin-trust/
├── backend/
│   ├── config/          # DB & Transporter configurations
│   ├── controllers/     # Route business logic (auth, matches, borrowers)
│   ├── middleware/      # Authentication & Error handlers
│   ├── models/          # Mongoose collections schemas
│   ├── utils/           # Trust rating engine & AI tools
│   └── server.js        # Entrypoint application file
├── frontend/
│   ├── public/          # Assets and icons
│   ├── src/
│   │   ├── api/         # Axios interceptors & endpoints
│   │   ├── components/  # Forms, buttons, cards
│   │   ├── context/     # React authentication state providers
│   │   ├── layouts/     # Master layout shells
│   │   └── pages/       # Router pages
│   └── vite.config.js   # Vite bundle rules
└── docs/                # Project documentation guides

Detailed details are available in the Database Documentation.

---

🚀 Installation & Setup

Prerequisites

• Node.js (v18.x or v20.x recommended)
• MongoDB account (local installation or Atlas cluster)

1. Clone the Repository

git clone https://github.com/codedbyanup/Fin-trust.git
cd Fin-trust

2. Configure Backend

cd backend
npm install
cp .env.example .env

Update .env with your variables:

PORT=5000
MONGO_URI=mongodb+srv://your_connection_string
JWT_SECRET=your_secret_key
EMAIL_USER=your_email
EMAIL_PASS=your_email_app_password
BREVO_API_KEY=your_brevo_key
GEMINI_API_KEY=your_gemini_key

Start the development server:

npm run dev

3. Configure Frontend

cd ../frontend
npm install
cp .env.example .env

Update .env:

VITE_API_URL=http://localhost:5000/api

Start the client application:

npm run dev

---

📘 Documentation Links

Detailed design specifications can be found under the /docs directory:

• 🏗️ System Architecture: Diagrams, workflows, and calculations.
• 🔌 API Documentation: Request formats, status codes, and endpoint guides.
• 💾 Database Design: ER diagram, validation fields, and collection tables.
• ☁️ Deployment Guide: Render, Vercel, and email SMTP bypass rules.

---

⚡ Performance Optimizations

• Lazy Loading: Router components use React's lazy and Suspense boundaries to load assets dynamically, reducing first-paint time.
• Fast Connection Awaiting: Server does not start listening on the port until MongoDB has completed its connection handshakes, avoiding timed-out request blocks.
• SMTP Bypass: Deliveries of emails utilize Brevo/Resend HTTP endpoints directly on port 443 to bypass port blocks on hosting environments.

---

🛡️ Security Practices

• Password Encryption: Automated hashing with salt factor 10 using bcryptjs on user schema hooks.
• Fail-Fast Connections: Added timeout limits (serverSelectionTimeoutMS: 5000) on Mongoose to prevent application locks.
• stateless JWT Authorization: Bearer token checks validation strictly on protected routing middlewares.
• CORS Constraints: Origin checks validate headers against domain configurations.

---

🗺️ Future Roadmap

• Instant Chat Messages: Direct chat channels between accepted matches.
• Repayment Tracking: Payment schedule logs and installment calculations.
• Mobile App: React Native wrapper app targeting iOS & Android devices.
• Advanced Credit Bureau Sync: Syncing with credit registries to import historical metrics.

---

🤝 Contribution Guidelines

We welcome community contributions. To contribute:

1. Fork this project.
2. Create a branch (git checkout -b feature/AmazingFeature).
3. Commit your changes (git commit -m 'feat: add amazing feature').
4. Push to the branch (git push origin feature/AmazingFeature).
5. Open a Pull Request.

---

✍️ Author Info

• Author: Anup Kodase
• GitHub: @codedbyanup
• LinkedIn: linkedin.com/in/anup-t-3a3763331
• Email: anupkodase@gmail.com