Deployment Guide

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/templates/fragments/layout.html
• src/main/resources/static/js/app.js
• src/main/java/com/paymaster/backend/presentation/controller/HomeController.java
• src/main/resources/templates/contracts/form.html

This guide provides instructions for building, configuring, and deploying the PayMaster Installment Management System. The application is a self-contained Spring Boot web application that uses an in-memory H2 database.

The system is designed as a monolithic web application where the backend, built with Spring Boot, serves server-side rendered HTML pages using Thymeleaf. The frontend incorporates client-side JavaScript for dynamic functionality and improved user experience.

1. System Architecture

The application follows a classic three-tier architecture. The backend is a Spring Boot application containing the web, business logic, and data access layers. It uses an embedded H2 database for data persistence during runtime.

This diagram illustrates the high-level architecture of the PayMaster application.

2. Prerequisites

To build and run the application, the following software must be installed on the target machine:

• Java Development Kit (JDK): Version 21 is specified.
• Apache Maven: To manage dependencies and build the project.

An internet connection is required during the build process to download Maven dependencies and for the client browser to fetch frontend assets from CDNs.

Sources: pom.xml:24

3. Dependencies

The application relies on several key frameworks and libraries for its backend and frontend functionality.

3.1. Backend Dependencies

The core backend dependencies are managed by Maven.

Group ID	Artifact ID	Version	Scope	Description
org.springframework.boot	spring-boot-starter-parent	3.2.0	-	Parent POM providing dependency management for Spring Boot.
org.springframework.boot	spring-boot-starter-web	-	Compile	For building web applications, including RESTful APIs and an embedded Tomcat server.
org.springframework.boot	spring-boot-starter-data-jpa	-	Compile	Provides data access layer using Java Persistence API with Hibernate.
org.springframework.boot	spring-boot-starter-thymeleaf	-	Compile	Server-side Java template engine for the view layer.
com.h2database	h2	-	Runtime	In-memory SQL database. Data is not persisted across application restarts.
com.github.mfathi91	persian-date-time	4.2.1	Compile	Library for handling Persian (Jalali) dates.
org.projectlombok	lombok	-	Optional	Reduces boilerplate code for model and entity classes.

Sources: pom.xml:11-74

3.2. Frontend Dependencies

Frontend assets are loaded directly from public Content Delivery Networks (CDNs).

Library	URL
Bootstrap 5.3.2 CSS	https://cdn.jsdelivr.net/npm/bootstrap@5.3.2/dist/css/bootstrap.rtl.min.css
Bootstrap Icons 1.11.1	https://cdn.jsdelivr.net/npm/bootstrap-icons@1.11.1/font/bootstrap-icons.css
Vazirmatn Font	https://cdn.jsdelivr.net/gh/rastikerdar/vazirmatn@v33.003/Vazirmatn-font-face.css
Bootstrap 5.3.2 JS Bundle	https://cdn.jsdelivr.net/npm/bootstrap@5.3.2/dist/js/bootstrap.bundle.min.js
Chart.js 4.4.0	https://cdn.jsdelivr.net/npm/chart.js@4.4.0/dist/chart.umd.min.js

Sources: src/main/resources/templates/fragments/layout.html:9-15, src/main/resources/templates/fragments/layout.html:150-151

4. Build and Packaging

The application is packaged as an executable JAR file using the Spring Boot Maven plugin.

1. Navigate to the root directory of the project (where pom.xml is located).
2. Run the following Maven command:

   mvn clean package
   

3. This command will compile the code, run tests, and package the application into a single JAR file. The resulting artifact will be located in the target/ directory.

The final artifact name is defined in the pom.xml: paymaster-backend-1.0.0.jar.

Sources: pom.xml:16-18, pom.xml:90-101

5. Running the Application

Once the application is packaged, it can be run from the command line.

1. Navigate to the target/ directory.
2. Execute the following command:

   java -jar paymaster-backend-1.0.0.jar
   

3. Upon successful startup, a message will be displayed in the console, indicating that the application is running.

╔════════════════════════════════════════╗
║  🚀 PayMaster Started Successfully!    ║
║  📍 http://localhost:8081 (Default)   ║
║  📊 H2 Console: /h2-console           ║
╚════════════════════════════════════════╝

The application will be accessible at http://localhost:8081. The H2 in-memory database console can be accessed at http://localhost:8081/h2-console.

Sources: src/main/java/com/paymaster/backend/PayMasterApplication.java:15-22

6. Configuration

The application is designed to run with minimal configuration.

6.1. Backend Configuration

No application.properties or application.yml file is included in the source, so the application runs on Spring Boot's default settings, with the following observations from the code:

• Server Port: The startup message indicates the application runs on port 8081.
• Database: The h2 dependency is scoped to runtime, which typically configures an in-memory database by default with Spring Boot. The data will be lost when the application is shut down.

Sources: src/main/java/com/paymaster/backend/PayMasterApplication.java:19, pom.xml:49-53

6.2. Frontend Configuration

The main JavaScript file contains a global configuration object.

// src/main/resources/static/js/app.js:12-20
const CONFIG = {
    apiBaseUrl: '/api',
    debounceDelay: 300,
    animationDuration: 300,
    toastDuration: 5000,
    dateFormat: 'YYYY/MM/DD',
    currency: 'ریال',
    locale: 'fa-IR'
};

This object defines the base path for API calls (/api), UI behavior timings, and localization settings.

Sources: src/main/resources/static/js/app.js:12-20

6.3. API Endpoint Inconsistency

There is a notable inconsistency between the API endpoint defined in the backend controller and the endpoint called by the frontend JavaScript.

• The HomeController defines an endpoint for installment calculation at GET /api/calculate.
• The frontend JavaScript in both app.js and an inline script in contracts/form.html attempts to call GET /api/calculate-installments.

This will result in a 404 Not Found error when the frontend tries to calculate installments. To fix this, either the backend controller method mapping must be changed to /api/calculate-installments or the frontend fetch URLs must be updated to /api/calculate.

Sources: src/main/java/com/paymaster/backend/presentation/controller/HomeController.java:381, src/main/resources/static/js/app.js:283, src/main/resources/templates/contracts/form.html:203