Technology Stack
Relevant source files
The following files were used as context for generating this wiki page:- pom.xml
- src/main/java/org/example/Main.java
- src/main/resources/static/css/style.css
- src/main/resources/static/js/app.js
- src/main/resources/templates/contracts/form.html
- src/main/resources/templates/contracts/list.html
- src/main/resources/templates/customers/form.html
- src/main/resources/templates/customers/list.html
- src/main/resources/templates/error.html
- src/main/resources/templates/fragments/layout.html
- src/main/resources/templates/installments/list.html
- src/main/resources/templates/reports/index.html
The PayMaster application is a full-stack web application built using a modern Java-based backend and a dynamic, responsive frontend. The backend is powered by the Spring Boot framework, which handles business logic, data persistence, and serving web pages. The frontend leverages the Thymeleaf templating engine for server-side rendering, enhanced with vanilla JavaScript for client-side interactivity, and styled with Bootstrap and custom CSS for a polished user interface.
This document outlines the core technologies, libraries, and architectural patterns used throughout the project, covering the backend, frontend, database, and build tooling.
Backend Technology
The backend is built on the Spring Boot ecosystem, utilizing Java 21. It follows a traditional Model-View-Controller (MVC) architecture where Spring handles web requests, business logic, and data access, while Thymeleaf renders the views.
Sources: pom.xml
Core Frameworks & Dependencies
The application's foundation is defined by the dependencies listed in the pom.xml file.
| Group ID | Artifact ID | Version | Description |
|---|---|---|---|
org.springframework.boot | spring-boot-starter-parent | 3.2.0 | Parent POM providing dependency management and default configurations for Spring Boot. |
org.springframework.boot | spring-boot-starter-web | - | Provides support for building web applications, including RESTful applications, using Spring MVC. Includes an embedded Tomcat server. |
org.springframework.boot | spring-boot-starter-data-jpa | - | Provides data persistence support using the Java Persistence API (JPA) with Hibernate as the default implementation. |
org.springframework.boot | spring-boot-starter-thymeleaf | - | Integrates the Thymeleaf templating engine for server-side rendering of HTML views. |
org.springframework.boot | spring-boot-starter-validation | - | Provides bean validation support using Hibernate Validator. |
com.h2database | h2 | - | An in-memory/embedded database, used with runtime scope, likely for development and testing. |
org.projectlombok | lombok | - | A library to reduce boilerplate code for model/data objects (e.g., getters, setters, constructors). |
com.github.mfathi91 | persian-date-time | 4.2.1 | A library for handling Persian (Jalali) calendar dates and times. |
org.springframework.boot | spring-boot-devtools | - | Provides development-time tools like automatic restarts and live reloading. |
Sources: pom.xml:11-15, 29-76
Backend Architecture Overview
The following diagram illustrates the high-level components of the backend system.
This diagram shows how a user request flows through the Spring MVC entry point to controllers, services, and repositories, ultimately interacting with the H2 database via JPA. Thymeleaf is used to render the final HTML response.
Sources: pom.xml
Build System
The project uses Apache Maven for dependency management and building the application. The spring-boot-maven-plugin is configured to create an executable JAR file.
Sources: pom.xml:80-92
Frontend Technology
The frontend is a multi-faceted system combining server-side rendering with client-side enhancements. It uses standard web technologies (HTML, CSS, JS) augmented by several libraries for UI, interactivity, and data visualization.
Sources: src/main/resources/templates/fragments/layout.html, src/main/resources/static/js/app.js, src/main/resources/static/css/style.css
Core Libraries and Frameworks
The UI is built upon the Bootstrap framework and enriched with data visualizations from Chart.js.
| Technology | Version | Description | Source |
|---|---|---|---|
| Bootstrap | 5.3.2 | A popular CSS framework for building responsive, mobile-first websites. Used for layout, components, and styling. | layout.html:9 |
| Bootstrap Icons | 1.11.1 | A library of SVG icons designed to work with Bootstrap. | layout.html:11 |
| Chart.js | 4.4.0 | A JavaScript library for creating responsive and animated charts and graphs. | layout.html:121, reports/index.html:62 |
| Vazirmatn Font | 33.003 | A Persian font used for consistent typography. | layout.html:13 |
| Thymeleaf | 3.2.0 (via Spring) | A server-side Java template engine for processing and creating HTML, XML, etc. | pom.xml:41, layout.html:2 |
Sources: src/main/resources/templates/fragments/layout.html:9-15, 121, pom.xml:41-44
Custom JavaScript Application (app.js)
A significant portion of the frontend logic is encapsulated in app.js. This file defines a modular architecture within an Immediately Invoked Function Expression (IIFE) to avoid polluting the global scope.
The main modules include:
CONFIG: Global configuration object for settings like API base URL, debounce delay, and date formats.Utils: A collection of utility functions for number formatting, date validation, and showing toast notifications.ApiService: A service layer for makingfetchrequests to the backend API (prefixed with/api).FormValidator: Manages form validation, including real-time checks for national codes and mobile numbers by calling the API.ContractCalculator: Handles the dynamic calculation of installment plans on the contract form, interacting with the/api/calculate-installmentsendpoint.DataTable: Provides enhancements for HTML tables, such as live search.UIComponents: Initializes and manages Bootstrap components like tooltips, modals, and popovers.
Sources: src/main/resources/static/js/app.js
Custom Styling (style.css)
The application features a custom stylesheet that defines a unique visual identity. Key features include:
- CSS Custom Properties (Variables): A comprehensive set of variables for colors, shadows, and border-radii, allowing for easy theming.
- RTL Support: Specific styles for right-to-left layout (
[dir="rtl"]). - Custom Components: Styles for non-standard components like
stats-card,empty-state, andspinner-overlay. - Responsive Design: Media queries to adapt the layout for different screen sizes.
Sources: src/main/resources/static/css/style.css:10-45, 70-72, 616-635
Client-Server Interaction
The application employs a hybrid model for client-server communication, using both server-side rendering via Thymeleaf and client-side API calls via JavaScript's fetch API.
- Initial Page Load: The browser requests a URL. Spring MVC routes the request to a controller, which prepares a model with data and returns a view name. Thymeleaf processes the corresponding HTML template, populates it with data from the model, and sends the complete HTML page to the browser.
- Dynamic Actions: For interactive features like form validation or calculations, the client-side JavaScript (
app.js) makes asynchronousfetchrequests to a RESTful API exposed by the backend (e.g.,/api/...). The backend processes the request and returns a JSON response, which the JavaScript then uses to update the UI without a full page reload.
Sequence Diagram: Contract Calculation
This diagram illustrates the flow for the contract calculation feature, which combines both server-side rendering and client-side API calls.
This flow demonstrates how the initial form is rendered by the server, while subsequent calculations are handled dynamically on the client side by calling a dedicated API endpoint.
Sources: src/main/resources/templates/contracts/form.html, src/main/resources/static/js/app.js:296-397