{"id":25929487,"url":"https://github.com/kei-k23/loan-tracker-service","last_synced_at":"2026-04-11T06:44:09.518Z","repository":{"id":280268281,"uuid":"941463238","full_name":"Kei-K23/loan-tracker-service","owner":"Kei-K23","description":"🏦 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.","archived":false,"fork":false,"pushed_at":"2025-03-02T11:05:40.000Z","size":140,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-02T12:19:27.961Z","etag":null,"topics":["automation","backend","cronjob-scheduler","nestjs","nodejs","postgresql","prisma-orm","restful-api"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Kei-K23.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-03-02T11:00:26.000Z","updated_at":"2025-03-02T11:05:44.000Z","dependencies_parsed_at":"2025-03-02T12:19:32.885Z","dependency_job_id":"65206ecb-8bf9-46c5-a264-89c136ff4372","html_url":"https://github.com/Kei-K23/loan-tracker-service","commit_stats":null,"previous_names":["kei-k23/loan-tracker-service"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kei-K23%2Floan-tracker-service","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kei-K23%2Floan-tracker-service/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kei-K23%2Floan-tracker-service/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kei-K23%2Floan-tracker-service/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Kei-K23","download_url":"https://codeload.github.com/Kei-K23/loan-tracker-service/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241746810,"owners_count":20013164,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","backend","cronjob-scheduler","nestjs","nodejs","postgresql","prisma-orm","restful-api"],"created_at":"2025-03-03T22:07:32.743Z","updated_at":"2025-12-01T15:02:25.787Z","avatar_url":"https://github.com/Kei-K23.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"### Loan Tracker Service: System Architecture\n\nThis 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.\n\nCheckout architecture hand-drawing in [Excalidraw](https://excalidraw.com/#json=MUO6NKTmmj9Y4Y6sSaAbc,19-hq5jTrJDFR2ZPLFpavw)\n\n![Drawing1](/public/img/img1.png)\n\n![Drawing2](/public/img/img2.png)\n\n---\n\n## **1. High-Level Architecture Overview**\n\nThe system is divided into several layers and components, each responsible for specific functionality:\n\n1. **API Layer**: Handles incoming HTTP requests and routes them to the appropriate service.\n2. **Service Layer**: Contains business logic and interacts with the database via Prisma ORM.\n3. **Data Access Layer**: Manages database operations using Prisma.\n4. **Authentication \u0026 Authorization Layer**: Handles JWT-based authentication and role-based access control.\n5. **Background Jobs Layer**: Manages cron jobs for sending email reminders and handling overdue payments.\n6. **Logging \u0026 Monitoring Layer**: Tracks system activity and errors for debugging and auditing.\n\n---\n\n## **2. Detailed Architecture**\n\n### **2.1 API Layer**\n\n- **Framework**: NestJS\n- **Responsibilities**:\n  - Expose RESTful APIs for client applications.\n  - Validate incoming requests using **class-validator** and **class-transformer**.\n  - Apply **rate limiting** to prevent abuse (e.g., using `@nestjs/throttler`).\n  - Handle errors and return standardized responses.\n\n#### Key Endpoints:\n\n- **Auth**: `/auth/login`, `/auth/register`, `/auth/refresh-token`\n- **Users**: `/users`, `/users/:id`, `/users/:id/loans`\n- **Loans**: `/loans`, `/loans/:id`, `/loans/:id/payments`\n- **Payments**: `/payments`, `/payments/:id`\n- **Notifications**: `/notifications`, `/notifications/:id`\n- **Profile**: `/profile`, `/profile/:id`\n- **Audit Logs**: `/audit-logs`\n\n---\n\n### **2.2 Service Layer**\n\n- **Responsibilities**:\n  - Implement business logic (e.g., loan approval, payment processing).\n  - Interact with the **Data Access Layer** (Prisma) to perform CRUD operations.\n  - Trigger background jobs (e.g., email reminders for overdue payments).\n\n#### Key Services:\n\n- **AuthService**: Handles user authentication and JWT token generation.\n- **UserService**: Manages user-related operations (e.g., CRUD, role assignment).\n- **LoanService**: Manages loan creation, approval, and status updates.\n- **PaymentService**: Handles payment processing and overdue penalty calculations.\n- **NotificationService**: Sends notifications to users (e.g., payment reminders).\n- **ProfileService**: Manages user profile information.\n- **AuditLogService**: Logs user actions for auditing purposes.\n\n---\n\n### **2.3 Data Access Layer**\n\n- **ORM**: Prisma\n- **Database**: PostgreSQL\n- **Responsibilities**:\n  - Define database models and relationships (as shown in your Prisma schema).\n  - Perform CRUD operations using Prisma Client.\n  - Handle database migrations.\n\n#### Key Models:\n\n- **User**: Stores user information and roles.\n- **Loan**: Tracks loan details, status, and associated payments.\n- **Payment**: Records payments made against loans.\n- **Notification**: Stores notifications for users.\n- **Profile**: Stores user profile details.\n- **AuditLog**: Logs user actions for auditing.\n\n---\n\n### **2.4 Authentication \u0026 Authorization Layer**\n\n- **Authentication**: JWT (JSON Web Tokens)\n  - Users log in with their credentials and receive a JWT.\n  - The JWT contains the user's ID, role, and expiration time.\n  - JWTs are validated on each request to ensure the user is authenticated.\n- **Authorization**: Role-Based Access Control (RBAC)\n  - Users are assigned roles (`ADMIN`, `USER`).\n  - Guards are used to restrict access to endpoints based on roles (e.g., only `ADMIN` can approve loans).\n\n#### Key Components:\n\n- **JWTAuthGuard**: Ensures the user is authenticated using JWT.\n- **RolesGuard**: Restricts access based on user roles.\n\n---\n\n### **2.5 Background Jobs Layer**\n\n- **Library**: `@nestjs/schedule` for cron jobs.\n- **Responsibilities**:\n  - Send email reminders for upcoming payments.\n  - Check for overdue payments and apply penalties.\n  - Send notifications to users for important events (e.g., loan approval).\n\n#### Key Jobs:\n\n- **Payment Reminder Job**:\n  - Runs daily to check for payments due in the next 3 days.\n  - Sends email reminders to users.\n- **Overdue Payment Job**:\n  - Runs daily to check for overdue payments.\n  - Applies penalty fees and updates loan status to `OVERDUE`.\n  - Sends notifications to users.\n\n---\n\n### **2.6 Logging \u0026 Monitoring Layer**\n\n- Log all incoming requests and responses.\n- Log errors and exceptions for debugging.\n- Track user actions for auditing (stored in the `AuditLog` table).\n\n#### Key Features:\n\n- **Request Logging**: Logs method, URL, status code, and response time.\n- **Error Logging**: Logs stack traces and error details.\n- **Audit Logging**: Logs user actions (e.g., loan approval, payment processing).\n\n---\n\n## **3. Best Practices**\n\n### **3.1 Security**\n\n- Use **HTTPS** to encrypt data in transit.\n- Hash passwords using **argon2**.\n- Validate and sanitize all user inputs to prevent SQL injection and XSS attacks using Pipe, Interceptor.\n\n### **3.2 Rate Limiting**\n\n- Apply rate limiting to prevent abuse (e.g., 100 requests per minute per user).\n- Use `@nestjs/throttler` to implement rate limiting.\n\n### **3.3 Error Handling**\n\n- Use NestJS's built-in exception filters to handle errors.\n- Return standardized error responses (e.g., `{ statusCode: 400, message: \"Bad Request\" }`).\n\n### **3.4 Testing (Future)**\n\n- Write unit tests for services and controllers using **Jest**.\n- Write integration tests to test API endpoints.\n- Use mocking to isolate dependencies\n\n### **3.5 Documentation**\n\n- Use **Swagger** to document APIs.\n- Provide clear documentation for each endpoint, including request/response examples.\n\n---\n\n## **4. Deployment**\n\n### **4.1 Environment Variables**\n\n- Store sensitive information (e.g., database URL, JWT secret) in environment variables.\n- Use `.env` files for local development.\n\n### **4.2 Database**\n\n- Use **PostgreSQL** as the primary database.\n- Set up automated backups and monitoring (Future).\n\n### **4.3 Hosting (Future)**\n\n- Use **Docker** for containerization.\n\n### **4.4 CI/CD (Future)**\n\n- Set up a CI/CD pipeline (e.g., GitHub Actions) for automated testing and deployment.\n\n---\n\n## **5. Example Workflow**\n\n1. **User Registration**:\n\n   - A user registers via `/auth/register`.\n   - Their password is hashed and stored in the database.\n   - A JWT is generated and returned to the client.\n\n2. **Loan Application**:\n\n   - A user applies for a loan via `/loans`.\n   - The loan is created with a `PENDING` status.\n   - An `ADMIN` or `MANAGER` approves the loan, updating its status to `APPROVED`.\n\n3. **Payment Processing**:\n\n   - A user makes a payment via `/payments`.\n   - The payment is recorded, and the loan's `totalPaid` is updated.\n   - If the payment is overdue, a penalty is applied.\n\n4. **Email Reminders**:\n\n   - A cron job checks for upcoming payments and sends email reminders.\n\n5. **Audit Logging**:\n   - All user actions (e.g., loan approval, payment processing) are logged in the `AuditLog` table.\n\n---\n\n## **6. Tools \u0026 Libraries**\n\n- **NestJS**: Framework for building scalable server-side applications.\n- **Prisma**: ORM for database access.\n- **PostgreSQL**: Relational database.\n- **JWT**: For authentication.\n- **@nestjs/throttler**: For rate limiting.\n- **@nestjs/schedule**: For cron jobs.\n- **Nodemailer**: For sending emails.\n- **Scalar/Swagger**: For beautiful API documentation.\n- **Docker**: For containerization and easy deployment.\n\n---\n\n## **7**. TODO\n\n- Profile Management\n- JWT Refresh Token\n- Logging with Winston\n\n---\n\nThis architecture ensures security, scalability, and maintainability while following best practices of build backend service and handling complex business logic.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkei-k23%2Floan-tracker-service","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkei-k23%2Floan-tracker-service","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkei-k23%2Floan-tracker-service/lists"}