/tiknet10-byte/paymaster-v3

Wiki directory

Browse AI-generated documentation for any repository.

Home

Relevant source files

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

PayMaster is a web-based installment management system designed to handle customers, contracts, and payments. The application is built using the Spring Boot framework for the backend and Thymeleaf for server-side rendering of the user interface. The "Home" or main entry point of the application is the dashboard, which provides a high-level overview of the system's status, including key statistics and lists of upcoming and overdue installments.

The system's architecture is centered around a main HomeController which manages routing for all primary features like customers, contracts, and reports. The frontend is a multi-page application with a consistent layout provided by shared Thymeleaf fragments, enhanced with client-side JavaScript for dynamic functionality, API interactions, and UI improvements.

Sources: pom.xml:16, src/main/java/com/paymaster/backend/PayMasterApplication.java, src/main/java/com/paymaster/backend/presentation/controller/HomeController.java:41-55

Project Architecture and Technologies

The application follows a standard Spring Boot project structure. The backend is powered by Java 21 and Spring Boot 3.2.0, utilizing Spring Data JPA for database interaction and an in-memory H2 database for runtime. The frontend uses Thymeleaf for templating, styled with Bootstrap 5 and a custom stylesheet. Client-side interactivity is managed by a core app.js file and Chart.js for data visualization.

Sources: pom.xml:22, pom.xml:34, pom.xml:46, src/main/resources/templates/fragments/layout.html:121

Technology Stack

Layer	Technology/Library	Purpose
Backend	Java 21	Core programming language
	Spring Boot 3.2.0	Application framework
	Spring Web	Building web applications, MVC architecture
	Spring Data JPA	Data access layer abstraction
	Thymeleaf	Server-side Java template engine
	H2 Database	In-memory relational database (runtime)
	Lombok	Reduces boilerplate code (e.g., getters/setters)
Frontend	Bootstrap 5.3.2	UI framework for styling and components
	Bootstrap Icons 1.11.1	Icon set
	Chart.js 4.4.0	Creating charts and graphs
	`app.js`	Custom client-side logic and API interactions
	`style.css`	Custom styling and theming

Sources: pom.xml:22-50, src/main/resources/templates/fragments/layout.html:8-14, src/main/resources/templates/fragments/layout.html:120-122, src/main/resources/static/css/style.css

High-Level Architecture

The diagram below illustrates the basic flow of a user request through the system.

Generating architecture diagram...

Sources: src/main/java/com/paymaster/backend/presentation/controller/HomeController.java, pom.xml:34, pom.xml:46

Application Entry and Initialization

The application is bootstrapped by the PayMasterApplication class, which contains the standard main method to run the Spring Boot application. On the client side, app.js serves as the entry point, initializing all frontend modules and components once the DOM is ready.

Backend Initialization

The PayMasterApplication.class is the entry point for the Java application. It uses the @SpringBootApplication annotation, which combines @Configuration, @EnableAutoConfiguration, and @ComponentScan.

Sources: src/main/java/com/paymaster/backend/PayMasterApplication.java:9

// src/main/java/com/paymaster/backend/PayMasterApplication.java:13-23
@SpringBootApplication
public class PayMasterApplication {
    public static void main(String[] args) {
        SpringApplication.run(PayMasterApplication.class, args);

        // نمایش پیام راه‌اندازی موفقیت‌آمیز در کنسول
        System.out.println("╔════════════════════════════════════════╗");
        System.out.println("║  🚀 PayMaster Started Successfully!    ║");
        System.out.println("║  📍 http://localhost:8081 (Default)   ║");
        System.out.println("║  📊 H2 Console: /h2-console           ║");
        System.out.println("╚════════════════════════════════════════╝");
    }
}

Frontend Initialization

The app.js file initializes various modules upon DOM content loaded. The main App.init() function orchestrates the setup of validators, UI components, and event listeners.

This diagram shows the frontend initialization flow.

Generating architecture diagram...

Sources: src/main/resources/static/js/app.js:1010-1024

Core Navigation and Layout

A consistent user experience is maintained across the application using a shared layout defined in src/main/resources/templates/fragments/layout.html. This file includes common UI elements like the main navigation bar and footer.

Main Navigation

The primary navigation is handled by a responsive navbar that provides access to all major sections of the application.

Link Text	Route Path	Icon Class	Controller Method
داشبورد (Dashboard)	`/dashboard` or `/`	`bi-speedometer2`	`HomeController.dashboard`
مشتریان (Customers)	`/customers`	`bi-people`	`HomeController.listCustomers`
قراردادها (Contracts)	`/contracts`	`bi-file-earmark-text`	`HomeController.listContracts`
اقساط (Installments)	(Dropdown)	`bi-credit-card`	-
- سررسید این هفته	`/installments/upcoming`	`bi-clock`	`HomeController.upcomingInstallments`
- اقساط معوق	`/installments/overdue`	`bi-exclamation-triangle`	`HomeController.overdueInstallments`
گزارش‌ها (Reports)	`/reports`	`bi-bar-chart`	`HomeController.reports`

Sources: src/main/resources/templates/fragments/layout.html:38-73, src/main/java/com/paymaster/backend/presentation/controller/HomeController.java

The Dashboard View

The dashboard is the application's home page, accessible via the / and /dashboard routes. It is managed by the dashboard method in HomeController. This method gathers key statistics and data from DashboardService and passes them to the dashboard.html view for rendering.

Dashboard Data Loading Sequence

This sequence diagram shows how the dashboard data is loaded and displayed when a user visits the home page.

Generating architecture diagram...

Sources: src/main/java/com/paymaster/backend/presentation/controller/HomeController.java:41-55

Frontend Core Services (`app.js`)

The app.js file provides a suite of services and utilities that power the client-side functionality of the application.

Global Configuration

A CONFIG object centralizes key settings for the frontend application.

Property	Default Value	Description
`apiBaseUrl`	`/api`	The base path for all API calls.
`debounceDelay`	`300`	Delay in milliseconds for debounce functions.
`toastDuration`	`5000`	Duration in milliseconds for toast messages.
`dateFormat`	`YYYY/MM/DD`	Standard date format.
`currency`	`ریال`	The currency symbol/name.
`locale`	`fa-IR`	The locale for number formatting.

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

Utility Functions (`Utils`)

The Utils object contains helper functions for common tasks like number formatting, validation, and UI interactions. Key functions include:

formatNumber(num): Formats a number with thousand separators for the fa-IR locale.
validateNationalCode(code): Performs local validation of an Iranian national ID.
validateMobile(mobile): Validates a mobile number format.
showToast(message, type): Displays a toast notification.
debounce(func, wait): A utility to limit the rate at which a function gets called.

Sources: src/main/resources/static/js/app.js:26-193

API Service (`ApiService`)

This service provides wrapper functions around the fetch API for making GET and POST requests to the backend. It simplifies API calls for features like live validation and data retrieval.

get(url, params): Performs a GET request.
post(url, data): Performs a POST request with a JSON body.
checkNationalCode(nationalCode, excludeId): Checks for the uniqueness of a national code via an API call.
calculateInstallments(principal, rate, months): Fetches installment calculation results from the server.

Sources: src/main/resources/static/js/app.js:199-278, src/main/resources/templates/contracts/form.html:241-249

Styling and Theming

The application's visual identity is defined in src/main/resources/static/css/style.css. It uses CSS Custom Properties (variables) for a consistent and easily maintainable color scheme and layout metrics.

Core Color Variables

Variable Name	Default Value	Usage
`--pm-primary`	`#3498db`	Main brand color for buttons, links.
`--pm-success`	`#2ecc71`	Success states, validation.
`--pm-warning`	`#f39c12`	Warnings, pending states.
`--pm-danger`	`#e74c3c`	Error states, deletion actions.
`--pm-dark`	`#2c3e50`	Primary text color.
`--pm-light`	`#ecf0f1`	Light backgrounds, borders.

Sources: src/main/resources/static/css/style.css:9-21

Home

Relevant source files

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

Sources: pom.xml:16, src/main/java/com/paymaster/backend/PayMasterApplication.java, src/main/java/com/paymaster/backend/presentation/controller/HomeController.java:41-55

Project Architecture and Technologies

Sources: pom.xml:22, pom.xml:34, pom.xml:46, src/main/resources/templates/fragments/layout.html:121

Technology Stack

Layer	Technology/Library	Purpose
Backend	Java 21	Core programming language
	Spring Boot 3.2.0	Application framework
	Spring Web	Building web applications, MVC architecture
	Spring Data JPA	Data access layer abstraction
	Thymeleaf	Server-side Java template engine
	H2 Database	In-memory relational database (runtime)
	Lombok	Reduces boilerplate code (e.g., getters/setters)
Frontend	Bootstrap 5.3.2	UI framework for styling and components
	Bootstrap Icons 1.11.1	Icon set
	Chart.js 4.4.0	Creating charts and graphs
	`app.js`	Custom client-side logic and API interactions
	`style.css`	Custom styling and theming

Sources: pom.xml:22-50, src/main/resources/templates/fragments/layout.html:8-14, src/main/resources/templates/fragments/layout.html:120-122, src/main/resources/static/css/style.css

High-Level Architecture

The diagram below illustrates the basic flow of a user request through the system.

Generating architecture diagram...

Sources: src/main/java/com/paymaster/backend/presentation/controller/HomeController.java, pom.xml:34, pom.xml:46

Application Entry and Initialization

Backend Initialization

Sources: src/main/java/com/paymaster/backend/PayMasterApplication.java:9

// src/main/java/com/paymaster/backend/PayMasterApplication.java:13-23
@SpringBootApplication
public class PayMasterApplication {
    public static void main(String[] args) {
        SpringApplication.run(PayMasterApplication.class, args);

        // نمایش پیام راه‌اندازی موفقیت‌آمیز در کنسول
        System.out.println("╔════════════════════════════════════════╗");
        System.out.println("║  🚀 PayMaster Started Successfully!    ║");
        System.out.println("║  📍 http://localhost:8081 (Default)   ║");
        System.out.println("║  📊 H2 Console: /h2-console           ║");
        System.out.println("╚════════════════════════════════════════╝");
    }
}

Frontend Initialization

The app.js file initializes various modules upon DOM content loaded. The main App.init() function orchestrates the setup of validators, UI components, and event listeners.

This diagram shows the frontend initialization flow.

Generating architecture diagram...

Sources: src/main/resources/static/js/app.js:1010-1024

Core Navigation and Layout

Main Navigation

The primary navigation is handled by a responsive navbar that provides access to all major sections of the application.

Link Text	Route Path	Icon Class	Controller Method
داشبورد (Dashboard)	`/dashboard` or `/`	`bi-speedometer2`	`HomeController.dashboard`
مشتریان (Customers)	`/customers`	`bi-people`	`HomeController.listCustomers`
قراردادها (Contracts)	`/contracts`	`bi-file-earmark-text`	`HomeController.listContracts`
اقساط (Installments)	(Dropdown)	`bi-credit-card`	-
- سررسید این هفته	`/installments/upcoming`	`bi-clock`	`HomeController.upcomingInstallments`
- اقساط معوق	`/installments/overdue`	`bi-exclamation-triangle`	`HomeController.overdueInstallments`
گزارش‌ها (Reports)	`/reports`	`bi-bar-chart`	`HomeController.reports`

Sources: src/main/resources/templates/fragments/layout.html:38-73, src/main/java/com/paymaster/backend/presentation/controller/HomeController.java

The Dashboard View

Dashboard Data Loading Sequence

This sequence diagram shows how the dashboard data is loaded and displayed when a user visits the home page.

Generating architecture diagram...

Sources: src/main/java/com/paymaster/backend/presentation/controller/HomeController.java:41-55

Frontend Core Services (`app.js`)

The app.js file provides a suite of services and utilities that power the client-side functionality of the application.

Global Configuration

A CONFIG object centralizes key settings for the frontend application.

Property	Default Value	Description
`apiBaseUrl`	`/api`	The base path for all API calls.
`debounceDelay`	`300`	Delay in milliseconds for debounce functions.
`toastDuration`	`5000`	Duration in milliseconds for toast messages.
`dateFormat`	`YYYY/MM/DD`	Standard date format.
`currency`	`ریال`	The currency symbol/name.
`locale`	`fa-IR`	The locale for number formatting.

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

Utility Functions (`Utils`)

The Utils object contains helper functions for common tasks like number formatting, validation, and UI interactions. Key functions include:

formatNumber(num): Formats a number with thousand separators for the fa-IR locale.
validateNationalCode(code): Performs local validation of an Iranian national ID.
validateMobile(mobile): Validates a mobile number format.
showToast(message, type): Displays a toast notification.
debounce(func, wait): A utility to limit the rate at which a function gets called.

Sources: src/main/resources/static/js/app.js:26-193

API Service (`ApiService`)

This service provides wrapper functions around the fetch API for making GET and POST requests to the backend. It simplifies API calls for features like live validation and data retrieval.

get(url, params): Performs a GET request.
post(url, data): Performs a POST request with a JSON body.
checkNationalCode(nationalCode, excludeId): Checks for the uniqueness of a national code via an API call.
calculateInstallments(principal, rate, months): Fetches installment calculation results from the server.

Sources: src/main/resources/static/js/app.js:199-278, src/main/resources/templates/contracts/form.html:241-249

Styling and Theming

Core Color Variables

Variable Name	Default Value	Usage
`--pm-primary`	`#3498db`	Main brand color for buttons, links.
`--pm-success`	`#2ecc71`	Success states, validation.
`--pm-warning`	`#f39c12`	Warnings, pending states.
`--pm-danger`	`#e74c3c`	Error states, deletion actions.
`--pm-dark`	`#2c3e50`	Primary text color.
`--pm-light`	`#ecf0f1`	Light backgrounds, borders.

Sources: src/main/resources/static/css/style.css:9-21

Home

Project Architecture and Technologies

Technology Stack

High-Level Architecture

Application Entry and Initialization

Backend Initialization

Frontend Initialization

Core Navigation and Layout

Main Navigation

The Dashboard View

Dashboard Data Loading Sequence

Frontend Core Services (app.js)

Global Configuration

Utility Functions (Utils)

API Service (ApiService)

Styling and Theming

Core Color Variables

Home

Project Architecture and Technologies

Technology Stack

High-Level Architecture

Application Entry and Initialization

Backend Initialization

Frontend Initialization

Core Navigation and Layout

Main Navigation

The Dashboard View

Dashboard Data Loading Sequence

Frontend Core Services (app.js)

Global Configuration

Utility Functions (Utils)

API Service (ApiService)

Styling and Theming

Core Color Variables

Frontend Core Services (`app.js`)

Utility Functions (`Utils`)

API Service (`ApiService`)

Frontend Core Services (`app.js`)

Utility Functions (`Utils`)

API Service (`ApiService`)