Architecture Overview

Relevant source files

The following files were used as context for generating this wiki page:

• pom.xml
• src/main/java/com/paymaster/backend/domain/entity/Contract.java
• src/main/java/com/paymaster/backend/domain/service/DashboardService.java
• src/main/java/com/paymaster/backend/presentation/controller/HomeController.java
• src/main/resources/static/js/app.js
• src/main/resources/templates/contracts/form.html
• src/main/resources/templates/fragments/layout.html

PayMaster is an installment management system built using the Spring Boot framework. Its architecture follows a traditional N-tier layered pattern, separating presentation, business logic, and data access. The application is a server-side rendered monolith, where the backend handles both business logic and UI rendering via Thymeleaf templates. The frontend is enhanced with vanilla JavaScript for dynamic features like AJAX calculations and client-side validation, providing a responsive user experience without being a full Single-Page Application (SPA).

The core of the application revolves around managing Customers, Contracts, and their associated Installments. The system is designed with a clear separation of concerns, making it maintainable and scalable for its intended purpose.

1. Technology Stack

The project is built on the Java ecosystem, leveraging the Spring Boot framework to simplify configuration and development. The key technologies are defined in the pom.xml file.

Technology	Purpose	Source
Java 21	Core programming language.	pom.xml:21
Spring Boot 3.2.0	Foundation framework for building the web application.	pom.xml:11
Spring Web	Handles HTTP requests, REST controllers, and MVC architecture.	pom.xml:25-28
Spring Data JPA	Simplifies data access layer by using repositories.	pom.xml:29-32
Thymeleaf	Server-side Java template engine for rendering HTML views.	pom.xml:33-36
H2 Database	In-memory database used for development and runtime data storage.	pom.xml:42-46
Maven	Dependency management and project build tool.	pom.xml
Lombok	Reduces boilerplate code for model/entity classes (e.g., getters).	pom.xml:48-52
persian-date-time	Library for handling Jalali (Persian) calendar dates.	pom.xml:54-58
Bootstrap 5 & Icons	Frontend CSS framework and icon set for UI components.	fragments/layout.html:8-10
Chart.js	JavaScript library for creating charts and data visualizations.	fragments/layout.html:78, app.js
Vanilla JavaScript (ES6)	Client-side scripting for interactivity, validation, and API calls.	app.js

2. Application Layers

The application is structured into distinct layers, each with a specific responsibility. This promotes a clean separation of concerns.

This diagram illustrates the layered architecture of the PayMaster application.

2.1. Presentation Layer

This layer is responsible for handling incoming HTTP requests and rendering the user interface.

• Controllers: The primary controller is HomeController.java. It uses Spring MVC annotations (@Controller, @GetMapping, @PostMapping) to map URLs to specific Java methods. These methods process user input, interact with the service layer, and return the name of a Thymeleaf template to be rendered.
• Views (Thymeleaf): The UI is constructed using Thymeleaf templates located in src/main/resources/templates. These files (*.html) are server-side rendered. They combine standard HTML with Thymeleaf's special attributes (th:*) to display dynamic data passed from the controllers. Reusable UI components like the navbar and footer are defined in fragments/layout.html and included in other pages.
• Static Assets: Frontend assets like CSS (style.css) and JavaScript (app.js) are served from src/main/resources/static.

Key Endpoints

The HomeController defines the main routes for the application:

Method	Path	Description	Source File
GET	/, /dashboard	Displays the main dashboard with statistics.	HomeController.java:41-55
GET	/customers	Lists all customers with pagination and search.	HomeController.java:61-77
POST	/customers/save	Saves a new or updated customer.	HomeController.java:88-113
GET	/contracts	Lists contracts, with optional filtering by status.	HomeController.java:152-176
GET	/contracts/new	Displays the form to create a new contract.	HomeController.java:182-193
POST	/contracts/save	Creates a new contract and its associated installments.	HomeController.java:198-223
GET	/contracts/view/{id}	Shows the details of a specific contract and its installments.	HomeController.java:228-243
POST	/installments/pay/{id}	Records a payment for a specific installment.	HomeController.java:296-318
GET	/api/calculate	An AJAX endpoint to calculate installment details.	HomeController.java:362-373

2.2. Service Layer

This layer contains the core business logic of the application. Services like DashboardService and ContractService orchestrate operations by coordinating with one or more repositories.

• DashboardService.java: Aggregates data from other services (CustomerService, ContractService, InstallmentService) to compile statistics for the main dashboard, such as total customers, active contracts, and financial summaries.
• ContractService.java: Manages the lifecycle of contracts, including creation, cancellation, and retrieval. It's responsible for complex operations like generating installments when a new contract is created.

Sources: DashboardService.java:23-42, HomeController.java:208-211

2.3. Data Access Layer (Repositories)

This layer is responsible for all database interactions. It uses Spring Data JPA, which automatically generates repository implementations based on interfaces. Although ContractRepository.java is not fully provided, its usage is implied by the service layer. These interfaces extend JpaRepository, providing standard CRUD (Create, Read, Update, Delete) operations out of the box.

2.4. Data Model (Entities)

Entities are plain Java objects (POJOs) annotated with JPA (jakarta.persistence.*) to map them to database tables.

• Contract.java: This is a central entity in the system. It defines the structure of a contract, including its financial details, status, and relationships with other entities.

The diagram below shows the relationship between the Contract, Customer, and Installment entities.

Sources: Contract.java

3. Frontend Architecture

The frontend is built with a server-side rendering approach using Thymeleaf, enhanced with client-side JavaScript for a more dynamic user experience.

• UI Components: The UI is built with Bootstrap 5, providing a responsive layout and standard components like cards, tables, modals, and forms. Custom styles are defined in style.css.
• Client-Side Logic (app.js): A single JavaScript file, app.js, contains all the client-side logic. It's organized into modules (e.g., FormValidator, ContractCalculator, UIComponents) and follows modern JavaScript (ES6) practices.
• Interactivity: JavaScript is used for:
  • Form Validation: Real-time validation for fields like National Code and mobile number via AJAX calls to the backend.
  • AJAX Calculations: The "New Contract" form features a calculator that sends data to a backend API (/api/calculate-installments) and updates the UI without a page reload.
  • UI Enhancements: Initializing Bootstrap components (tooltips, modals), handling loading states on buttons, and managing toast notifications.

Data Flow: Contract Calculator

The following sequence diagram shows how the frontend and backend interact when the user changes a value in the contract creation form.

4. Conclusion

The architecture of PayMaster v3 is a well-structured, monolithic Spring Boot application. It effectively uses a layered design pattern to separate concerns between the UI, business logic, and data persistence. The choice of server-side rendering with Thymeleaf, augmented by targeted client-side JavaScript, provides a robust and maintainable solution for a data-driven web application of this scope. The use of Spring Data JPA and an in-memory H2 database simplifies development and data management.