Skip to content

architecture.md

Latest commit

 

History

History
93 lines (73 loc) · 4.05 KB

architecture.md

File metadata and controls

93 lines (73 loc) · 4.05 KB
Raw

Fin-Trust - System Architecture

This document describes the architectural layout, core subsystems, component interactions, and algorithms implemented in Fin-Trust.

🏛️ System Topology

Fin-Trust utilizes a client-server architecture with external system integrations.

graph TD
  User[Browser Frontend] -->|HTTPS Requests| Backend[Express Backend API]
  Backend -->|Mongoose ODM| DB[(MongoDB Database)]
  Backend -->|REST API| Gemini[Google Gemini AI API]
  Backend -->|HTTP POST| Brevo[Brevo SMTP / HTTP Email API]
  User -->|Read-Only Coordinates| Nominatim[OSM Nominatim API]
Loading

1. Presentation Layer (Frontend)

  • Framework: React 19 (Vite)
  • Styling: Tailwind CSS v4 & custom HSL-based design system
  • Motion/UX: GSAP (GreenSock Animation Platform) for fluid transitions, micro-animations, magnetic fields, and parallax cards.
  • Client routing: React Router DOM (v7) with protected route boundaries.

2. Business Logic Layer (Backend)

  • Framework: Node.js & Express
  • Session management: Stateless JSON Web Tokens (JWT)
  • Request logging: Morgan (Development environment)
  • File parsing: Multer (KyC file upload buffering)

3. Data Tier

  • Database: MongoDB Atlas
  • Object Modeling: Mongoose ODM with pre-save password-hashing hooks and schema-level projection exclusions.

🔄 Core Workflows

User Verification & Authentication

sequenceDiagram
    autonumber
    actor User
    participant Frontend
    participant Backend
    participant Brevo as Brevo API
    
    User->>Frontend: Fill Registration Form
    Frontend->>Backend: POST /api/auth/register
    Backend->>Backend: Create user (isVerified: false)
    Backend->>Backend: Generate & hash 6-digit OTP
    Backend->>Brevo: Send OTP email (or debugOtp in dev)
    Backend-->>Frontend: Response 201 (Pending verification)
    Frontend->>User: Redirect to Verify Email page
    User->>Frontend: Input OTP
    Frontend->>Backend: POST /api/auth/verify-email
    Backend->>Backend: Compare hashes & verify
    Backend-->>Frontend: Response 200 (Success)
    Frontend->>User: Allow login
Loading

🧮 Subsystems & Core Algorithms

1. Proximity Tracker (Haversine Formula)

Fin-Trust calculates the physical distance between matched borrowers and lenders dynamically on the backend. This is implemented via the Haversine formula, which computes the shortest distance between two points on the surface of a sphere given their longitudes and latitudes.

$$d = 2R \arcsin\left(\sqrt{\sin^2\left(\frac{\Delta \phi}{2}\right) + \cos(\phi_1)\cos(\phi_2)\sin^2\left(\frac{\Delta \lambda}{2}\right)}\right)$$

Where:

  • $R$ is the Earth's radius (6,371 km or 6,371,000 meters).
  • $\phi_1, \phi_2$ are the latitudes of point 1 and point 2 in radians.
  • $\Delta \phi$ is the difference in latitudes.
  • $\Delta \lambda$ is the difference in longitudes.

2. Trust Score Engine

The system assigns a standard rating score from 0 to 100 based on specific profile parameters:

  • Income-to-Loan Ratio (Up to 30 points): Computed by dividing the requested loan amount by monthly income.
  • Employment Status (Up to 20 points): Salaried profiles receive 20 points, Self-Employed receive 15 points, and Unemployed receive 0 points.
  • Document Verification via AI OCR (Up to 35 points):
    • 10 points per uploaded document (Aadhaar, PAN, Bank Statement).
    • 5 points if the user's registered profile name matches the names parsed from the uploaded documents by the OCR engine.
  • Profile Completeness (Up to 15 points): Points awarded for completing all bio fields.

3. Weighted Matching Engine

Matches are ranked using a multi-factor scoring formula:

  1. Location Match (25%): Proximity matching of cities and actual coordinates.
  2. Lending Range Fit (30%): Verification of whether the requested borrower amount fits within the lender's threshold limits.
  3. Trust Score compliance (30%): Borrower's calculated trust score must meet the lender's minimum score constraints.
  4. Duration Fit (15%): Proximity of requested repayment durations.