Contribution Guidelines
Relevant source files
The following files were used as context for generating this wiki page: - [pom.xml](https://github.com/tiknet10-byte/paymaster-v3/blob/HEAD/pom.xml) - [src/main/java/com/paymaster/backend/presentation/controller/HomeController.java](https://github.com/tiknet10-byte/paymaster-v3/blob/HEAD/src/main/java/com/paymaster/backend/presentation/controller/HomeController.java) - [src/main/resources/static/css/style.css](https://github.com/tiknet10-byte/paymaster-v3/blob/HEAD/src/main/resources/static/css/style.css) - [src/main/resources/static/js/app.js](https://github.com/tiknet10-byte/paymaster-v3/blob/HEAD/src/main/resources/static/js/app.js) - [src/main/resources/templates/fragments/layout.html](https://github.com/tiknet10-byte/paymaster-v3/blob/HEAD/src/main/resources/templates/fragments/layout.html) - [src/main/resources/templates/customers/form.html](https://github.com/tiknet10-byte/paymaster-v3/blob/HEAD/src/main/resources/templates/customers/form.html) - [src/main/resources/templates/contracts/form.html](https://github.com/tiknet10-byte/paymaster-v3/blob/HEAD/src/main/resources/templates/contracts/form.html) - [src/main/resources/templates/customers/list.html](https://github.com/tiknet10-byte/paymaster-v3/blob/HEAD/src/main/resources/templates/customers/list.html) - [src/main/resources/templates/reports/index.html](https://github.com/tiknet10-byte/paymaster-v3/blob/HEAD/src/main/resources/templates/reports/index.html)This document outlines the coding conventions, architectural patterns, and best practices for contributing to the PayMaster v3 project. Adhering to these guidelines ensures code consistency, maintainability, and quality. The project is a Spring Boot application utilizing Java for the backend and Thymeleaf, JavaScript, and Bootstrap for the frontend.
Project Setup
The project is built using Apache Maven. Key configuration details can be found in the pom.xml file.
- Java Version: The project requires Java 21.
- Spring Boot Version: It is based on Spring Boot
3.2.0. - Dependencies: Core dependencies are managed in
pom.xml.
Key Dependencies
| Group ID | Artifact ID | Description |
|---|---|---|
org.springframework.boot | spring-boot-starter-web | Core dependency for building web applications. |
org.springframework.boot | spring-boot-starter-data-jpa | Provides JPA support with Hibernate. |
org.springframework.boot | spring-boot-starter-thymeleaf | Server-side Java template engine for the view layer. |
org.springframework.boot | spring-boot-starter-validation | Provides validation capabilities. |
com.h2database | h2 | In-memory database for development and testing. |
org.projectlombok | lombok | Reduces boilerplate code for model/data objects. |
com.github.mfathi91 | persian-date-time | Library for handling Persian (Jalali) dates. |
Sources: pom.xml:19-22, 28-63
Backend Development
The backend is built with Spring Boot and follows a layered architecture. The primary entry point for web requests is the HomeController.
Sources: src/main/java/com/paymaster/backend/presentation/controller/HomeController.java
Controller and Routing
All web page and API endpoint routing is managed within HomeController. When adding new features, adhere to the existing RESTful conventions.
- Page Rendering: Methods that render Thymeleaf templates should return a
Stringcorresponding to the template path (e.g.,"customers/list"). - API Endpoints: Endpoints intended for AJAX calls should be prefixed with
/api/and annotated with@ResponseBody. - Redirection: Use
redirect:/pathfor post-submission redirects. Flash attributes (RedirectAttributes) should be used to pass success or error messages.
The following diagram illustrates the request flow for saving a new customer.
API Endpoints
The application exposes several API endpoints for client-side functionality. These are primarily used by app.js for features like live validation and calculations.
| Method | Path | Description | Controller Method |
|---|---|---|---|
GET | /api/calculate | Calculates installment details for a contract. | calculateInstallment |
GET | /api/check-national-code | Validates and checks for duplicate national codes. | (Not in HomeController) |
GET | /api/check-mobile | Checks for duplicate mobile numbers. | (Not in HomeController) |
Sources: src/main/java/com/paymaster/backend/presentation/controller/HomeController.java:400-415, src/main/resources/static/js/app.js:254-262, src/main/resources/templates/customers/form.html:120-127
Coding Conventions
- Dependency Injection: Use constructor injection with
@RequiredArgsConstructorfrom Lombok. - Comments: Use Javadoc-style comments for public methods, explaining their purpose, as seen in
HomeController. - Services: Business logic should be encapsulated in service classes (e.g.,
CustomerService,ContractService) and injected into the controller.
Sources: src/main/java/com/paymaster/backend/presentation/controller/HomeController.java:25-33, 39-43
Frontend Development
The frontend uses Thymeleaf for server-side rendering, enhanced with vanilla JavaScript and styled with Bootstrap.
CSS Styling
All custom styles are located in style.css. Contributions should follow the established structure and conventions.
- CSS Variables: The stylesheet heavily utilizes CSS variables (Custom Properties) for theming, colors, shadows, and spacing. Always use these variables instead of hardcoded values.
- Structure: The file is organized into numbered sections (e.g.,
1.ROOT VARIABLES,5.CARDS,8.FORMS). New styles should be added to the appropriate section. - Naming Convention: A custom prefix
--pm-is used for all variables (e.g.,--pm-primary,--pm-shadow).
Color Palette
| Variable Name | Color | Usage |
|---|---|---|
--pm-primary | #3498db | Main brand color, links, active states. |
--pm-success | #2ecc71 | Success states, validation. |
--pm-danger | #e74c3c | Error states, deletion actions. |
--pm-warning | #f39c12 | Warnings, pending states. |
--pm-dark | #2c3e50 | Main text color. |
--pm-gray-light | #bdc3c7 | Borders, placeholders. |
--pm-light | #ecf0f1 | Light backgrounds. |
Sources: src/main/resources/static/css/style.css:11-44
JavaScript (app.js)
The main JavaScript file, app.js, is structured as an IIFE (Immediately Invoked Function Expression) containing several modules.
This diagram shows the modular structure of app.js.
Key JavaScript Modules
CONFIG: A global configuration object for settings like API base URL, debounce delay, and date formats.Utils: Contains helper functions for number formatting (formatNumber), validation (validateNationalCode), and UI feedback (showToast).ApiService: A wrapper around thefetchAPI for makingGETandPOSTrequests to the backend.FormValidator: Manages real-time form validation for fields like national code and mobile number by callingApiService.ContractCalculator: Handles the logic for the contract calculation form, fetching results from the backend and updating the UI and chart.App.init(): The main entry point that initializes all modules when the DOM is ready.
Sources: src/main/resources/static/js/app.js:10-995
HTML and Thymeleaf
The view layer is built with Thymeleaf templates.
- Layout: A consistent layout is maintained using Thymeleaf fragments. The main layout is defined in
fragments/layout.html, which includes the head, navbar, footer, and scripts. - Fragments: When creating new pages, use
th:replaceto include common fragments.
Sources: src/main/resources/templates/fragments/layout.html:1-120, src/main/resources/templates/customers/list.html:3, 6, 163, 164<head th:replace="~{fragments/layout :: head('Page Title')}"></head> <nav th:replace="~{fragments/layout :: navbar}"></nav> <footer th:replace="~{fragments/layout :: footer}"></footer> <div th:replace="~{fragments/layout :: scripts}"></div> - Forms: Forms should use Bootstrap's validation classes (
needs-validation,is-invalid). Client-side validation logic is handled inapp.js. For example, the customer form includes inputs with specific IDs (nationalCode,mobile) that are targeted by theFormValidatormodule.
Sources: src/main/resources/templates/customers/form.html:26-80, src/main/resources/static/js/app.js:312-421 - Charts: The application uses
Chart.jsfor data visualization. Chart initialization scripts are typically embedded directly in the relevant HTML file (e.g.,reports/index.html) and use data passed from the backend via Thymeleaf'sth:inline="javascript".
Sources: src/main/resources/templates/reports/index.html:68-109, src/main/resources/templates/contracts/form.html:170-201