Payroll Management System

Overview

The Payroll Management System is a Spring Boot-based application designed to manage employee payrolls, including employee details, employment records, deductions, and payslips. The system supports role-based access control with JWT authentication, automated payroll generation, and email notifications for payslip approvals. It uses Spring Data JPA for database interactions and MySQL as the database.

Features

Employee Management: CRUD operations for employee personal information, with role-based security (ROLE_MANAGER, ROLE_ADMIN, ROLE_EMPLOYEE).
Employment Management: Manage employment details such as department, position, and base salary.
Deduction Management: Configure and apply deductions (e.g., EmployeeTax, Pension, MedicalInsurance, Housing, Transport) to payroll calculations.
Payroll Processing: Generate payslips for active employees, ensuring deductions do not exceed gross salary. Approve payslips and send email notifications.
Security: JWT-based authentication (using email and password) and role-based authorization.
Email Notifications: Automated email notifications triggered by database routines when payslip status changes to PAID.

System Flow Diagram

can be found in

Entity-Relationship Diagram (ERD)

The ERD represents the database schema:

erDiagram
    Employee ||--o{ Employment : has
    Employee ||--o{ PaySlip : receives

    Employee {
        Long id PK
        String code UNIQUE
        String firstName
        String lastName
        String email UNIQUE
        String password
        Role role
        String mobile
        LocalDate dateOfBirth
        EmployeeStatus status "ACTIVE, DISABLED"
        boolean emailVerified
    }

    Employment {
        Long id PK
        String code
        Long employee_id FK
        String department
        String position
        BigDecimal baseSalary
        EmploymentStatus status "ACTIVE, INACTIVE"
        LocalDate joiningDate
    }

    Deduction {
        Long id PK
        String code
        String name
        BigDecimal percentage
    }

    PaySlip {
        Long id PK
        Long employee_id FK
        BigDecimal houseAmount
        BigDecimal transportAmount
        BigDecimal employeeTaxedAmount
        BigDecimal pensionAmount
        BigDecimal medicalInsuranceAmount
        BigDecimal otherTaxedAmount
        BigDecimal grossSalary
        BigDecimal netSalary
        int month
        int year
        PaySlipStatus status "PENDING, PAID"
    }

The diagram is rendered automatically in GitHub and other Markdown viewers that support Mermaid.

Architecture

Presentation Layer: RESTful APIs via Spring MVC controllers.
Security Layer: JWT-based authentication and role-based authorization using Spring Security.
Service Layer: Business logic for employee, employment, deduction, and payroll management.
Persistence Layer: Spring Data JPA with Hibernate for PostgreSQL database interactions.
Integration Layer: SMTP server for email notifications, triggered by database routines.

Tech Stack

Backend Framework: Spring Boot 3.x
ORM: Spring Data JPA with Hibernate
Database: PostgreSQL
Security: Spring Security with JWT (jjwt library)
Email: Spring Boot Starter Mail
Dependencies:
- spring-boot-starter-web
- spring-boot-starter-data-jpa
- spring-boot-starter-security
- spring-boot-starter-mail
- postgresql
- jjwt
- lombok
Build Tool: Maven
Database Migration: Flyway (optional)
Testing: JUnit, Mockito
Email Testing: MailHog (recommended for local SMTP testing)

POJOs

Employee: id, code, firstName, lastName, email, password, roles, mobile, dateOfBirth, status (ACTIVE, DISABLED)
Employment: id, code, employee (FK), department, position, baseSalary, status (ACTIVE, INACTIVE), joiningDate
Deduction: id, code, name, percentage
PaySlip: id, employee (FK), houseAmount, transportAmount, employeeTaxedAmount, pensionAmount, medicalInsuranceAmount, otherTaxedAmount, grossSalary, netSalary, month, year, status (PENDING, PAID)
EmailNotification: id, employeeId, message, createdAt
DTOs: EmployeeDTO, DeductionDTO, LoginRequest, JwtResponse

Security Implementation

Authentication: Via /api/auth/login using email and password, generating a JWT token.
Authorization: Role-based access control:
- ROLE_MANAGER: Manage employees, deductions, and generate payroll.
- ROLE_ADMIN: Approve payslips.
- ROLE_EMPLOYEE: View personal details and payslips.
JWT: Signed with HS512, expires after 7 days, includes roles.
Password Security: Hashed with BCrypt.
CSRF/CORS: CSRF disabled for stateless APIs; CORS configurable.

Endpoints

Authentication

POST /api/auth/login: Authenticate and return JWT token.
- Request: {"email": "string", "password": "string"}
- Response: {"token": "string"}
- Access: Public

Employee Management

POST /api/employee: Create employee (ROLE_MANAGER).
GET /api/employee/{id}: Get employee details (ROLE_MANAGER, ROLE_ADMIN, ROLE_EMPLOYEE for self).
PUT /api/employee/{id}: Update employee (ROLE_MANAGER).
DELETE /api/employee/{id}: Disable employee (ROLE_MANAGER).
GET /api/employee/me: Get authenticated employee’s details (ROLE_EMPLOYEE, ROLE_MANAGER, ROLE_ADMIN).

Employment Management

POST /api/employment: Create employment record (ROLE_MANAGER).
GET /api/employment/{id}: Get employment details (ROLE_MANAGER, ROLE_ADMIN).
PUT /api/employment/{id}: Update employment (ROLE_MANAGER).
DELETE /api/employment/{id}: Deactivate employment (ROLE_MANAGER).

Deduction Management

POST /api/deduction: Create deduction (ROLE_MANAGER).
GET /api/deduction/{id}: Get deduction (ROLE_MANAGER).
GET /api/deduction/all: Get all deductions (ROLE_MANAGER).
PUT /api/deduction/{id}: Update deduction (ROLE_MANAGER).
DELETE /api/deduction/{id}: Delete deduction (ROLE_MANAGER).