https://github.com/kei-k23/loan-tracker-service

🏦 The Loan Tracker Service is a backend system that allows users to apply for loans, track their payments, receive notifications, and manage their accounts. The system is built using Node.js/NestJS, Prisma ORM, and PostgreSQL, with a focus on security, scalability, and maintainability.
https://github.com/kei-k23/loan-tracker-service

automation backend cronjob-scheduler nestjs nodejs postgresql prisma-orm restful-api

Last synced: 3 months ago
JSON representation

🏦 The Loan Tracker Service is a backend system that allows users to apply for loans, track their payments, receive notifications, and manage their accounts. The system is built using Node.js/NestJS, Prisma ORM, and PostgreSQL, with a focus on security, scalability, and maintainability.

• Host: GitHub
• URL: https://github.com/kei-k23/loan-tracker-service
• Owner: Kei-K23
• Created: 2025-03-02T11:00:26.000Z (over 1 year ago)
• Default Branch: main
• Last Pushed: 2025-03-02T11:05:40.000Z (over 1 year ago)
• Last Synced: 2025-03-02T12:19:27.961Z (over 1 year ago)
• Topics: automation, backend, cronjob-scheduler, nestjs, nodejs, postgresql, prisma-orm, restful-api
• Language: TypeScript
• Homepage:
• Size: 137 KB
• Stars: 0
• Watchers: 1
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

README

          
### Loan Tracker Service: System Architecture

This document outlines the system architecture for the **Loan Tracker Service**, a backend service built using **Node.js/NestJS**, **Prisma ORM**, and **PostgreSQL**. The service is designed to manage loans, payments, user profiles, notifications, and audit logs. It incorporates best practices such as **API rate limiting**, **cron jobs for email reminders**, **JWT-based authentication**, **role-based access control (RBAC)**, and more.

Checkout architecture hand-drawing in [Excalidraw](https://excalidraw.com/#json=MUO6NKTmmj9Y4Y6sSaAbc,19-hq5jTrJDFR2ZPLFpavw)

![Drawing1](/public/img/img1.png)

![Drawing2](/public/img/img2.png)

---

## **1. High-Level Architecture Overview**

The system is divided into several layers and components, each responsible for specific functionality:

1. **API Layer**: Handles incoming HTTP requests and routes them to the appropriate service.

2. **Service Layer**: Contains business logic and interacts with the database via Prisma ORM.

3. **Data Access Layer**: Manages database operations using Prisma.

4. **Authentication & Authorization Layer**: Handles JWT-based authentication and role-based access control.

5. **Background Jobs Layer**: Manages cron jobs for sending email reminders and handling overdue payments.

6. **Logging & Monitoring Layer**: Tracks system activity and errors for debugging and auditing.

---

## **2. Detailed Architecture**

### **2.1 API Layer**

- **Framework**: NestJS

- **Responsibilities**:

  - Expose RESTful APIs for client applications.

  - Validate incoming requests using **class-validator** and **class-transformer**.

  - Apply **rate limiting** to prevent abuse (e.g., using `@nestjs/throttler`).

  - Handle errors and return standardized responses.

#### Key Endpoints:

- **Auth**: `/auth/login`, `/auth/register`, `/auth/refresh-token`

- **Users**: `/users`, `/users/:id`, `/users/:id/loans`

- **Loans**: `/loans`, `/loans/:id`, `/loans/:id/payments`

- **Payments**: `/payments`, `/payments/:id`

- **Notifications**: `/notifications`, `/notifications/:id`

- **Profile**: `/profile`, `/profile/:id`

- **Audit Logs**: `/audit-logs`

---

### **2.2 Service Layer**

- **Responsibilities**:

  - Implement business logic (e.g., loan approval, payment processing).

  - Interact with the **Data Access Layer** (Prisma) to perform CRUD operations.

  - Trigger background jobs (e.g., email reminders for overdue payments).

#### Key Services:

- **AuthService**: Handles user authentication and JWT token generation.

- **UserService**: Manages user-related operations (e.g., CRUD, role assignment).

- **LoanService**: Manages loan creation, approval, and status updates.

- **PaymentService**: Handles payment processing and overdue penalty calculations.

- **NotificationService**: Sends notifications to users (e.g., payment reminders).

- **ProfileService**: Manages user profile information.

- **AuditLogService**: Logs user actions for auditing purposes.

---

### **2.3 Data Access Layer**

- **ORM**: Prisma

- **Database**: PostgreSQL

- **Responsibilities**:

  - Define database models and relationships (as shown in your Prisma schema).

  - Perform CRUD operations using Prisma Client.

  - Handle database migrations.

#### Key Models:

- **User**: Stores user information and roles.

- **Loan**: Tracks loan details, status, and associated payments.

- **Payment**: Records payments made against loans.

- **Notification**: Stores notifications for users.

- **Profile**: Stores user profile details.

- **AuditLog**: Logs user actions for auditing.

---

### **2.4 Authentication & Authorization Layer**

- **Authentication**: JWT (JSON Web Tokens)

  - Users log in with their credentials and receive a JWT.

  - The JWT contains the user's ID, role, and expiration time.

  - JWTs are validated on each request to ensure the user is authenticated.

- **Authorization**: Role-Based Access Control (RBAC)

  - Users are assigned roles (`ADMIN`, `USER`).

  - Guards are used to restrict access to endpoints based on roles (e.g., only `ADMIN` can approve loans).

#### Key Components:

- **JWTAuthGuard**: Ensures the user is authenticated using JWT.

- **RolesGuard**: Restricts access based on user roles.

---

### **2.5 Background Jobs Layer**

- **Library**: `@nestjs/schedule` for cron jobs.

- **Responsibilities**:

  - Send email reminders for upcoming payments.

  - Check for overdue payments and apply penalties.

  - Send notifications to users for important events (e.g., loan approval).

#### Key Jobs:

- **Payment Reminder Job**:

  - Runs daily to check for payments due in the next 3 days.

  - Sends email reminders to users.

- **Overdue Payment Job**:

  - Runs daily to check for overdue payments.

  - Applies penalty fees and updates loan status to `OVERDUE`.

  - Sends notifications to users.

---

### **2.6 Logging & Monitoring Layer**

- Log all incoming requests and responses.

- Log errors and exceptions for debugging.

- Track user actions for auditing (stored in the `AuditLog` table).

#### Key Features:

- **Request Logging**: Logs method, URL, status code, and response time.

- **Error Logging**: Logs stack traces and error details.

- **Audit Logging**: Logs user actions (e.g., loan approval, payment processing).

---

## **3. Best Practices**

### **3.1 Security**

- Use **HTTPS** to encrypt data in transit.

- Hash passwords using **argon2**.

- Validate and sanitize all user inputs to prevent SQL injection and XSS attacks using Pipe, Interceptor.

### **3.2 Rate Limiting**

- Apply rate limiting to prevent abuse (e.g., 100 requests per minute per user).

- Use `@nestjs/throttler` to implement rate limiting.

### **3.3 Error Handling**

- Use NestJS's built-in exception filters to handle errors.

- Return standardized error responses (e.g., `{ statusCode: 400, message: "Bad Request" }`).

### **3.4 Testing (Future)**

- Write unit tests for services and controllers using **Jest**.

- Write integration tests to test API endpoints.

- Use mocking to isolate dependencies

### **3.5 Documentation**

- Use **Swagger** to document APIs.

- Provide clear documentation for each endpoint, including request/response examples.

---

## **4. Deployment**

### **4.1 Environment Variables**

- Store sensitive information (e.g., database URL, JWT secret) in environment variables.

- Use `.env` files for local development.

### **4.2 Database**

- Use **PostgreSQL** as the primary database.

- Set up automated backups and monitoring (Future).

### **4.3 Hosting (Future)**

- Use **Docker** for containerization.

### **4.4 CI/CD (Future)**

- Set up a CI/CD pipeline (e.g., GitHub Actions) for automated testing and deployment.

---

## **5. Example Workflow**

1. **User Registration**:

   - A user registers via `/auth/register`.

   - Their password is hashed and stored in the database.

   - A JWT is generated and returned to the client.

2. **Loan Application**:

   - A user applies for a loan via `/loans`.

   - The loan is created with a `PENDING` status.

   - An `ADMIN` or `MANAGER` approves the loan, updating its status to `APPROVED`.

3. **Payment Processing**:

   - A user makes a payment via `/payments`.

   - The payment is recorded, and the loan's `totalPaid` is updated.

   - If the payment is overdue, a penalty is applied.

4. **Email Reminders**:

   - A cron job checks for upcoming payments and sends email reminders.

5. **Audit Logging**:

   - All user actions (e.g., loan approval, payment processing) are logged in the `AuditLog` table.

---

## **6. Tools & Libraries**

- **NestJS**: Framework for building scalable server-side applications.

- **Prisma**: ORM for database access.

- **PostgreSQL**: Relational database.

- **JWT**: For authentication.

- **@nestjs/throttler**: For rate limiting.

- **@nestjs/schedule**: For cron jobs.

- **Nodemailer**: For sending emails.

- **Scalar/Swagger**: For beautiful API documentation.

- **Docker**: For containerization and easy deployment.

---

## **7**. TODO

- Profile Management

- JWT Refresh Token

- Logging with Winston

---

This architecture ensures security, scalability, and maintainability while following best practices of build backend service and handling complex business logic.