# Loan Aggregator Marketplace MVP - Implementation Plan (Backend)

## 1. Project Architecture & Scope

This project is a high-reliability, production-oriented backend for a **Loan Aggregator Marketplace**. It enables borrowers to discover, assess indicative eligibility for, and apply for loan products across multiple institutional lenders, while providing dedicated lender management and administrative oversight.

### Business Boundary & Regulatory Framing
- **Aggregator / Marketplace Boundary:** The platform acts strictly as a discovery, indicative comparison, referral, and application intake intermediary. Final credit underwriting, KYC verification, sanction, and disbursement are strictly executed by the respective partner lenders.
- Indicative results are never represented as guaranteed sanctions.

### Technology Stack
- **Runtime & Language:** Node.js (v20+ / v24+), TypeScript 5.x
- **Framework:** Express.js with modular REST routing
- **ORM & Database:** Prisma ORM with MySQL (Decimal types for monetary precision)
- **Validation:** Zod for all request bodies, queries, route parameters, and environment variables
- **Authentication & Security:** JWT (short-lived access tokens) + rotating refresh tokens in HttpOnly cookies, Bcrypt for password hashing, Helmet, CORS, Rate Limiting, Audit Logging
- **Documentation:** Swagger/OpenAPI 3.0 via `swagger-jsdoc` & `swagger-ui-express`
- **Testing:** Vitest / Jest, Supertest for API integration tests
- **Storage & Adapters:** Modular adapter pattern for Document Storage (S3 / Local private storage with signed URLs), Email (Console / SMTP adapter), SMS (Console / Twilio adapter), Mock Lender APIs, Mock KYC & Credit Bureau

---

## 2. Monorepo & Directory Structure

```text
loan-marketplace/
├── apps/
│   └── api/
│       ├── src/
│       │   ├── config/              # Environment variables, database, constants
│       │   ├── middleware/          # Auth, RBAC, tenant isolation, validation, rate-limiter, audit logger, error handler
│       │   ├── modules/
│       │   │   ├── auth/            # Registration, login, refresh, password reset, OTP
│       │   │   ├── borrower/        # Profile, saved offers, borrower application views
│       │   │   ├── marketplace/     # Loan products, categories, EMI calculator, indicative eligibility
│       │   │   ├── applications/    # Application state machine, assignment, notes, timeline
│       │   │   ├── documents/       # Upload/download signed URLs, signature validation, metadata
│       │   │   ├── lender/          # Lender onboarding, staff management, product CRUD, review
│       │   │   ├── admin/           # User management, lender approval, audit logs, system dashboard
│       │   │   ├── commissions/     # Commission rules, immutable ledger, reversals, reconciliation
│       │   │   └── integrations/    # Provider health, webhook handling, mock adapters
│       │   ├── integrations/        # Adapters: Lender, KYC, Credit Bureau, Storage, Notifications
│       │   ├── utils/               # EMI math, monetary decimal helpers, token helpers, file signature checks
│       │   ├── docs/                # OpenAPI/Swagger schemas and specs
│       │   ├── app.ts               # Express app configuration
│       │   └── server.ts            # HTTP server bootstrap
│       ├── prisma/
│       │   ├── schema.prisma        # 27+ normalized entities with Decimal money & foreign keys
│       │   ├── migrations/          # SQL migrations
│       │   └── seed.ts              # Idempotent seed script with lenders, products, rules, admins
│       ├── tests/
│       │   ├── unit/                # Math, eligibility, state machine, commission, validator tests
│       │   └── integration/         # Auth, RBAC, tenant isolation, application lifecycle tests
│       ├── tsconfig.json
│       └── package.json
├── packages/
│   └── shared/                      # Shared types, Zod schemas, constants, financial calculators
│       ├── src/
│       ├── tsconfig.json
│       └── package.json
├── docs/
│   ├── IMPLEMENTATION_PLAN.md       # Phased tracking & architecture
│   ├── API_DOCUMENTATION.md         # Full endpoint specifications
│   ├── SECURITY_GUIDELINES.md       # Financial security, RBAC & compliance
│   └── DEPLOYMENT.md                # Environment & production guide
├── scripts/                         # Database and development helper scripts
├── docker-compose.yml               # MySQL, Redis, local development services
├── .env.example                     # Full configuration specification
├── package.json                     # Monorepo workspaces
├── README.md                        # Setup and developer runbook
```

---

## 3. Database Schema Entities (Prisma / MySQL)

1. **User**: Authentication credentials, role (`BORROWER`, `LENDER_ADMIN`, `LENDER_STAFF`, `PLATFORM_ADMIN`), status (`ACTIVE`, `SUSPENDED`, `PENDING_VERIFICATION`).
2. **UserProfile**: Demographics, income, residential address, employment type, employer details.
3. **RefreshToken**: Cryptographic token hash, family ID, revoked status, expiry.
4. **ConsentRecord**: Terms of service, privacy policy, credit inquiry consent, timestamp, IP, version.
5. **Lender**: Institutional lender organization, registration number, contact, onboarding status (`DRAFT`, `SUBMITTED`, `UNDER_REVIEW`, `APPROVED`, `REJECTED`, `SUSPENDED`).
6. **LenderUser**: Mapping user to lender organization with specific permissions.
7. **LenderVerification**: Documents and audit trails for lender onboarding review.
8. **LoanCategory**: Configurable loan classifications (`PERSONAL_LOAN`, `HOME_LOAN`, `BUSINESS_LOAN`, `EDUCATION_LOAN`, etc.).
9. **LoanProduct**: Product catalog with interest rate bounds, tenure bounds, processing fee type (`FLAT` / `PERCENTAGE`), min/max fees, status (`DRAFT`, `ACTIVE`, `INACTIVE`).
10. **LoanProductVersion**: Versioned audit trail for interest rates, fees, and disclosure changes.
11. **EligibilityRule**: Configurable rule sets per lender or product (min income, age bounds, DTI max, employment categories).
12. **EligibilityAssessment**: Log of indicative eligibility evaluations, rule versions applied, and outcomes.
13. **SavedLoanOffer**: Bookmarked offers by borrowers with snapshot rates.
14. **LoanApplication**: Primary application record with unique reference code (`APP-YYYYMMDD-XXXX`), status, requested amount, tenure, assigned lender.
15. **ApplicationStatusHistory**: Strict state machine audit log (previous status, new status, actor ID, reason, timestamp).
16. **ApplicationAssignment**: History of assignments to lenders and lender officers.
17. **ApplicationNote**: Internal notes (Lender Staff / Admin only) and applicant messages (Borrower-visible).
18. **ApplicationDocument**: Private uploaded files (type, storage key, SHA256 checksum, MIME, verification status, scan status).
19. **Notification**: User notifications (title, content, category, read status).
20. **NotificationDelivery**: Multi-channel delivery tracking (Email, SMS, In-App).
21. **IntegrationProvider**: Provider registry (Mock Lender, Sandbox Bureau, Mock KYC, etc.).
22. **IntegrationCredentialReference**: Vault or encrypted key reference pointers (never raw secrets).
23. **IntegrationEvent**: Outbound/inbound integration log with correlation IDs, payloads, and response status.
24. **WebhookEvent**: Inbound webhook idempotency tracking with signature verification.
25. **ReferralAttribution**: Campaign code, source, click timestamp, attributed application ID.
26. **CommissionRule**: Applicable rates (flat or percentage of sanctioned/disbursed amount) per lender/category.
27. **CommissionLedgerEntry**: Immutable accounting entries (`PENDING`, `CONFIRMED`, `PAYABLE`, `PAID`, `REVERSED`, `CANCELLED`).
28. **AuditLog**: Cryptographically attributable logs of sensitive security and administrative actions.

---

## 4. Financial Calculation & Validation Engines

### Standard Reducing-Balance EMI Formula
$$EMI = \frac{P \times r \times (1 + r)^n}{(1 + r)^n - 1}$$
- $P$ = Principal loan amount
- $r$ = Monthly interest rate (Annual rate / 12 / 100)
- $n$ = Loan tenure in months
- **Zero-Interest Edge Case:** If $r = 0$, $EMI = \frac{P}{n}$.
- **Rounding:** Monetary values rounded to 2 decimal places using deterministic financial rounding; all DB storage uses `Decimal(12, 2)`.

### Indicative Eligibility Rules Engine
- Evaluates **Debt-To-Income (DTI)** ratio: $\text{Current Obligations} + \text{Indicative EMI} \le \text{Max Allowed DTI} \times \text{Monthly Income}$.
- Checks minimum income, age limits, acceptable employment types (Salaried, Self-Employed, etc.).
- Transparently returns criteria passed, failed, and calculated maximum indicative borrowing capacity.

---

## 5. Security & RBAC Matrix

| Capability / Endpoint | BORROWER | LENDER_STAFF | LENDER_ADMIN | PLATFORM_ADMIN |
| :--- | :---: | :---: | :---: | :---: |
| Register / Profile Edit | Own | None | None | All |
| Check Eligibility & EMI | Yes | Yes | Yes | Yes |
| Submit Loan Application | Own | No | No | On behalf / Test |
| Upload & View Documents | Own only | Assigned App only | Assigned App only | All |
| Update Application Status | Cancel/Withdraw | Permitted steps | Permitted steps | All |
| Manage Loan Products | No | View assigned | Manage own | All |
| Onboard Lenders | No | No | Submit details | Approve/Reject |
| Commission Ledger | No | No | View own | Manage & Settle |
| View System Audit Logs | No | No | No | Full access |

Tenant isolation is strictly verified at middleware and repository layers: a Lender can query only rows where `lenderId` matches their authenticated session.

---

## 6. Phase Breakdown & Progress Tracker

- [x] **Phase 1: Inspect & Plan** *(Completed)*
  - Monorepo design, toolchain inspection, comprehensive architecture plan, API specifications.
- [x] **Phase 2: Project Foundation** *(Completed)*
  - Monorepo workspaces (`apps/api`, `packages/shared`).
  - TypeScript, Express, Prisma ORM, MySQL connection.
  - Docker Compose, `.env.example`, health check endpoints.
- [x] **Phase 3: Core Authentication & RBAC** *(Completed)*
  - User model, Bcrypt password hashing, JWT access (15m) + refresh token rotation in HttpOnly cookies with token reuse detection.
  - Role-based authorization middleware (`BORROWER`, `LENDER_ADMIN`, `LENDER_STAFF`, `PLATFORM_ADMIN`), tenant isolation, rate limiting.
- [x] **Phase 4: Marketplace, Products & Calculators** *(Completed)*
  - Loan categories & products catalog across multiple lenders.
  - EMI calculator with zero-interest support, reducing-balance formula, 2-decimal rounding.
  - Indicative eligibility rules engine with full unit test coverage.
  - Comparison API endpoint (side-by-side comparison of 2 to 5 products).
- [x] **Phase 5: Applications & Secure Document Management** *(Completed)*
  - Application lifecycle state machine (`DRAFT` -> `SUBMITTED` -> `UNDER_REVIEW` -> `APPROVED`/`REJECTED`/`WITHDRAWN`/`CLOSED`).
  - Signed URL generation, document upload completion with magic byte validation (PDF, PNG, JPEG).
  - Application notes (internal vs applicant-visible), timeline, notification dispatcher.
- [x] **Phase 6: Lender Portal Backend** *(Completed)*
  - Lender onboarding workflow, verification status transitions.
  - Lender product management with versioning (`LoanProductVersion`).
  - Application review, status updates, tenant isolation enforcement.
- [x] **Phase 7: Admin Oversight & Commission Ledger** *(Completed)*
  - System dashboard metrics calculated via SQL aggregate queries from real database tables.
  - User and lender management endpoints with suspension/approval controls.
  - Commission rules and immutable ledger entries (disbursement milestones, transitions, CSV export).
- [x] **Phase 8: Integration Adapters (Mock & Modular)** *(Completed)*
  - Mock Lender adapter, Mock KYC adapter, Mock Credit Bureau adapter.
  - Development Notification adapter (Email/SMS).
  - Inbound webhook verification with HMAC-SHA256 signature check & duplicate event replay prevention.
- [x] **Phase 9: QA, Testing & Hardening** *(Completed)*
  - Unit tests: EMI calculator, zero interest, boundary values, eligibility engine, processing fee caps, magic byte inspector.
  - Integration tests: Auth validation, RBAC enforcement, marketplace endpoints, signed URL security, webhook verification.
  - 100% tests passing (32/32 tests).
  - Idempotent seed script (`seed.ts`) with realistic financial data.
- [x] **Phase 10: Production Readiness & Documentation** *(Completed)*
  - Swagger/OpenAPI documentation served at `/api/docs`.
  - Production build verification (`npm run build`).
  - Deployment runbook (`docs/DEPLOYMENT.md`), security guidelines (`docs/SECURITY_GUIDELINES.md`), API specification (`docs/API_DOCUMENTATION.md`), and quickstart `README.md`.

---

## 7. Verification Summary

- **Total Test Files:** 2 passed
- **Total Tests Executed:** 32 passed (17 Unit Tests, 15 API Integration Tests)
- **TypeScript Compilation:** Zero errors (`tsc --noEmit` passed on all workspaces)
- **Monorepo Build:** `@loan-marketplace/shared` and `@loan-marketplace/api` built successfully