Getting Started
Relevant source files
The following files were used as context for generating this wiki page:- pom.xml
- src/main/java/com/paymaster/backend/PayMasterApplication.java
- src/main/resources/static/js/app.js
- src/main/resources/static/css/style.css
- src/main/resources/templates/fragments/layout.html
- src/main/resources/templates/contracts/form.html
- src/main/resources/templates/customers/form.html
- src/main/resources/templates/customers/list.html
- src/main/resources/templates/contracts/list.html
- src/main/resources/templates/installments/list.html
- src/main/resources/templates/reports/index.html
This document provides a technical overview of the PayMaster application, an installment management system. It details the project's architecture, core technologies, and key functionalities to help developers understand the codebase and begin development. The application is built using Java and the Spring Boot framework, with a server-side rendered frontend using Thymeleaf and vanilla JavaScript.
The system manages customers, contracts, and their corresponding installment payments. It features a web interface for all CRUD operations, reporting dashboards, and real-time calculation and validation logic.
Sources: pom.xml:14, src/main/java/com/paymaster/backend/PayMasterApplication.java:6-8
Architecture and Technology Stack
The application follows a classic monolithic architecture, with a Spring Boot backend serving a Thymeleaf-based frontend. The backend handles business logic, data persistence, and API endpoints, while the frontend manages user interaction and presentation.
Sources: pom.xml, src/main/java/com/paymaster/backend/PayMasterApplication.java
Core Components Diagram
This diagram illustrates the high-level architecture of the PayMaster application.
Backend Technologies
The backend is built on the Spring Boot framework, leveraging several key starters for rapid development.
| Dependency | Version | Purpose |
|---|---|---|
spring-boot-starter-parent | 3.2.0 | Provides dependency and plugin management for the Spring Boot project. |
spring-boot-starter-web | - | For building web applications, including RESTful APIs. |
spring-boot-starter-data-jpa | - | For data persistence using Java Persistence API. |
spring-boot-starter-thymeleaf | - | Server-side Java template engine for the view layer. |
spring-boot-starter-validation | - | Provides validation capabilities (e.g., for form inputs). |
h2database | - | In-memory database for development and testing. |
lombok | - | Reduces boilerplate code for model/data objects. |
persian-date-time | 4.2.1 | A library for handling Persian (Jalali) calendar dates. |
The project is configured to run on Java 21.
Sources: pom.xml:9-63
Frontend Technologies
The frontend is built with standard web technologies, enhanced by libraries for styling and interactivity.
| Technology | Source | Purpose |
|---|---|---|
| Bootstrap 5 | https://cdn.jsdelivr.net/npm/bootstrap@5.3.2/... | Core CSS framework for layout, components, and responsive design. |
| Bootstrap Icons | https://cdn.jsdelivr.net/npm/bootstrap-icons@1.11.1/... | Icon set used throughout the UI. |
| Chart.js | https://cdn.jsdelivr.net/npm/chart.js@4.4.0/... | For rendering charts on the reports and contract pages. |
| Vazirmatn Font | https://cdn.jsdelivr.net/gh/rastikerdar/vazirmatn@v33.003/... | The primary font used for the Persian UI. |
| Custom CSS | src/main/resources/static/css/style.css | Custom styles, color variables, and component overrides. |
| Custom JS | src/main/resources/static/js/app.js | Main application logic, API calls, validation, and UI enhancements. |
Sources: src/main/resources/templates/fragments/layout.html:8-15, src/main/resources/templates/reports/index.html:86, src/main/resources/templates/contracts/form.html:246
Running the Application
The application is a standard Spring Boot project and can be run from the main class.
- Prerequisites: Java 21 and Maven must be installed.
- Execution: Run the
mainmethod inPayMasterApplication.java. - Access: Once started, the application is accessible at
http://localhost:8081(default port). - H2 Console: The in-memory H2 database console is available at
http://localhost:8081/h2-console.
Sources: src/main/java/com/paymaster/backend/PayMasterApplication.java:15-22
Frontend Core (app.js)
The file src/main/resources/static/js/app.js is the heart of the client-side functionality. It is structured into several modules that handle different aspects of the UI and user interaction.
Sources: src/main/resources/static/js/app.js
Key Modules in app.js
| Module | Description |
|---|---|
CONFIG | Global configuration object for API base URL, debounce delays, and localization settings. |
Utils | Utility functions for number/currency formatting, date/ID validation, and showing toast notifications. |
ApiService | A service layer for making fetch requests to the backend API endpoints. |
FormValidator | Handles real-time form validation, including asynchronous checks for national code and mobile number. |
ContractCalculator | Manages the real-time calculation of installment plans on the contract creation form. |
DataTable | Provides enhancements for HTML tables, such as live search. |
UIComponents | Initializes and manages Bootstrap components like tooltips, modals, and popovers. |
App | The main application object that initializes all other modules on DOMContentLoaded. |
Sources: src/main/resources/static/js/app.js:10-811
Client-Side API Endpoints
The ApiService module in app.js defines several functions that correspond to backend API endpoints. These are used for features like real-time validation and calculations.
| Method | HTTP Verb | Endpoint | Parameters | Description |
|---|---|---|---|---|
checkNationalCode | GET | /api/check-national-code | nationalCode, excludeId | Validates a national code for uniqueness. |
checkMobile | GET | /api/check-mobile | mobile, excludeId | Validates a mobile number for uniqueness. |
calculateInstallments | GET | /api/calculate-installments | principal, rate, months | Calculates total interest and installment amount. |
convertDate | GET | /api/convert-date | persianDate | Converts a Persian date string. |
searchCustomers | GET | /api/search-customers | q | Searches for customers by a query string. |
Sources: src/main/resources/static/js/app.js:270-316
Core Features
The application is organized around several key business domains, each with its own set of views and logic.
UI Module Navigation
The main navigation structure is defined in layout.html and provides access to the core modules of the application.
Customer Management
This feature allows for creating, viewing, updating, and deleting customers. The customer form includes client-side validation for fields like National Code and Mobile Number.
Validation Flow for National Code:
The following diagram shows the sequence of events when a user enters a national code in the customer form.
Contract Management
This feature handles the creation and management of installment contracts. The contract form includes a real-time calculator to preview installment details.
Installment Calculation Flow:
This diagram illustrates how the installment preview is calculated and displayed.