# vvr-vikram/hrms-service architecture

> Architecture diagram of the GitHub repository vvr-vikram/hrms-service, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vvr-vikram/hrms-service
- Repository: https://github.com/vvr-vikram/hrms-service

## Overview

#### Purpose and Runtime
`hrms-service` is a Java/Spring Boot REST backend for human-resources operations: employee records, attendance, leave, payroll, shifts, salary structures, and related employee data. The application starts at `src/main/java/com/oneenterprise/JrmsApplication.java`; Maven dependencies/build are defined in `pom.xml`.

#### API and Request Boundary
HTTP entry points are domain controllers: `src/main/java/com/oneenterprise/controller/EmployeeController.java`, `src/main/java/com/oneenterprise/controller/AttendanceController.java`, and `src/main/java/com/oneenterprise/controller/LeaveController.java` (plus payroll and authentication controllers). Requests and responses cross an explicit DTO boundary under `src/main/java/com/oneenterprise/dto/request` and `src/main/java/com/oneenterprise/dto/response`, rather than exposing persistence entities directly. Errors are normalized centrally by `src/main/java/com/oneenterprise/exception/GlobalExceptionHandler.java`.

#### Authentication, Authorization, and Cross-Cutting Audit
Security is configured in `src/main/java/com/oneenterprise/config/SecurityConfig.java`. JWT-bearing requests pass through `src/main/java/com/oneenterprise/security/JwtAuthenticationFilter.java`, using `src/main/java/com/oneenterprise/util/JwtTokenUtil.java`; `AuthController` is the authentication-facing endpoint. Audit behavior is separated from business services through `src/main/java/com/oneenterprise/audit/AuditAspect.java` and `src/main/java/com/oneenterprise/audit/AuditInterceptor.java`, with audit records modeled by `AuditLog.java`.

#### Core Service Layer
Controllers delegate to interfaces and implementations, keeping business workflows behind service boundaries: `src/main/java/com/oneenterprise/service/EmployeeService.java` / `src/main/java/com/oneenterprise/service/impl/EmployeeServiceImpl.java`, `src/main/java/com/oneenterprise/service/impl/LeaveServiceImpl.java`, and `src/main/java/com/oneenterprise/service/impl/PayrollServiceImpl.java`. This layer validates domain rules, coordinates repositories, translates entities via mappers, and returns response DTOs.

#### HR Domain and Persistence
JPA-style domain storage centers on employees and linked HR facts: `src/main/java/com/oneenterprise/entity/EmployeeEntity.java`, `src/main/java/com/oneenterprise/entity/AttendanceEntity.java`, `src/main/java/com/oneenterprise/entity/LeaveRequestEntity.java`, and payroll/payslip entities. Repository interfaces form the database boundary, including `src/main/java/com/oneenterprise/repository/EmployeeRepository.java`, `src/main/java/com/oneenterprise/repository/LeaveBalanceRepository.java`, and `src/main/java/com/oneenterprise/repository/PayrollRepository.java`. Mapper classes, such as `src/main/java/com/oneenterprise/mapper/EmployeeMapper.java`, isolate DTO/entity conversion.

#### Principal Workflow Areas
Employee management includes profile, skills, certifications, documents, and emergency contacts; creation emits `src/main/java/com/oneenterprise/event/EmployeeCreatedEvent.java`, handled by `EmployeeEventListener.java`. Attendance and overtime are processed through `AttendanceServiceImpl` and `OvertimeEntity`. Leave processing combines leave types, requests, approval input, statuses, and balances through `LeaveServiceImpl`, `LeaveRequestEntity`, and `LeaveBalanceEntity`. Payroll generation uses salary structures, payroll runs, and payslips through `PayrollServiceImpl`, `PayrollEntity`, and `PayslipEntity`.

#### Infrastructure and Lifecycle
Runtime configuration is in `src/main/resources/application.yml` with development overrides in `src/main/resources/application-dev.yml`. Database schema lifecycle is Flyway-style migration SQL: `src/main/resources/db/migration/V1__create_employee_tables.sql` and `V2__create_attendance_leave_payroll_tables.sql`. External-facing assumptions visible in the repository are an HTTP API client (the supplied `HRMS_Postman_Collection.json`), JWT authentication, and a relational database; no other remote service integration is represented.

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_controllers["HR controllers<br/>REST controllers"]
  node_dto["Request / response DTOs<br/>API contract"]
  node_errors["Global exception handler<br/>error boundary"]
end

subgraph group_security["Security &amp; Audit"]
  node_security_config["Security configuration<br/>Spring Security"]
  node_jwt_filter["JWT authentication filter<br/>security filter"]
  node_jwt_util["JWT token utility"]
  node_audit["Audit aspect and interceptor<br/>cross-cutting audit"]
end

subgraph group_core["HR Workflows"]
  node_employee_service["Employee service<br/>service boundary"]
  node_attendance_service["Attendance and overtime<br/>service workflow"]
  node_leave_service["Leave workflow<br/>service workflow"]
  node_payroll_service["Payroll workflow<br/>service workflow"]
  node_employee_event["Employee-created event<br/>domain event"]
end

subgraph group_data["Persistence"]
  node_mappers["Entity / DTO mappers<br/>mapping layer"]
  node_repositories["HR repositories<br/>JPA repository boundary"]
  node_hr_entities["HR entities<br/>JPA domain model"]
  node_database[("Relational database")]
end

node_app{{"Spring Boot application<br/>runtime"}}
node_runtime_config["Runtime configuration<br/>application config"]

node_app -->|"initializes"| node_security_config
node_app -->|"serves"| node_controllers
node_app -->|"loads"| node_runtime_config
node_security_config -->|"registers"| node_jwt_filter
node_jwt_filter -->|"validates tokens with"| node_jwt_util
node_controllers -->|"accepts and returns"| node_dto
node_controllers -.->|"errors handled by"| node_errors
node_controllers -->|"delegates employee operations"| node_employee_service
node_controllers -->|"delegates attendance operations"| node_attendance_service
node_controllers -->|"delegates leave operations"| node_leave_service
node_controllers -->|"delegates payroll operations"| node_payroll_service
node_employee_service -->|"publishes on creation"| node_employee_event
node_employee_service -->|"maps through"| node_mappers
node_leave_service -->|"maps through"| node_mappers
node_payroll_service -->|"maps through"| node_mappers
node_employee_service -->|"coordinates"| node_repositories
node_attendance_service -->|"coordinates"| node_repositories
node_leave_service -->|"coordinates"| node_repositories
node_payroll_service -->|"coordinates"| node_repositories
node_repositories -->|"persists"| node_hr_entities
node_repositories -->|"reads and writes"| node_database
node_audit -.->|"audits"| node_employee_service
node_audit -.->|"audits"| node_leave_service
node_audit -.->|"audits"| node_payroll_service

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_controllers,node_dto,node_errors toneBlue
class node_security_config,node_jwt_filter,node_jwt_util,node_audit toneAmber
class node_employee_service,node_attendance_service,node_leave_service,node_payroll_service,node_employee_event toneMint
class node_mappers,node_repositories,node_hr_entities,node_database toneRose
class node_app,node_runtime_config toneNeutral
```

## Components

### HTTP API

- **HR controllers**: REST controllers · Employee, attendance, leave, payroll, and authentication endpoints.
- **Request / response DTOs**: API contract · Separates HTTP payloads from entities.
- **Global exception handler**: error boundary · Normalizes API errors.

### Security & Audit

- **Security configuration**: Spring Security
- **JWT authentication filter**: security filter
- **JWT token utility**: token utility
- **Audit aspect and interceptor**: cross-cutting audit · Captures audited operations as audit logs.

### HR Workflows

- **Employee service**: service boundary · Manages employee profiles and related employee data.
- **Attendance and overtime**: service workflow
- **Leave workflow**: service workflow · Processes leave requests, approvals, statuses, and balances.
- **Payroll workflow**: service workflow · Generates payroll runs and payslips from salary structures.
- **Employee-created event**: domain event · Handled after employee creation.

### Persistence

- **Entity / DTO mappers**: mapping layer
- **HR repositories**: JPA repository boundary · Employee, leave-balance, and payroll repository interfaces.
- **HR entities**: JPA domain model · Employees, attendance, leave requests, payroll, payslips, and overtime.
- **Relational database**: database · Schema is managed through Flyway migrations.

### Other components

- **Spring Boot application**: runtime · Bootstraps the REST service.
- **Runtime configuration**: application config

## Connections

- Spring Boot application → Security configuration: initializes
- Spring Boot application → HR controllers: serves
- Spring Boot application → Runtime configuration: loads
- Security configuration → JWT authentication filter: registers
- JWT authentication filter → JWT token utility: validates tokens with
- HR controllers → Request / response DTOs: accepts and returns
- HR controllers → Global exception handler: errors handled by
- HR controllers → Employee service: delegates employee operations
- HR controllers → Attendance and overtime: delegates attendance operations
- HR controllers → Leave workflow: delegates leave operations
- HR controllers → Payroll workflow: delegates payroll operations
- Employee service → Employee-created event: publishes on creation
- Employee service → Entity / DTO mappers: maps through
- Leave workflow → Entity / DTO mappers: maps through
- Payroll workflow → Entity / DTO mappers: maps through
- Employee service → HR repositories: coordinates
- Attendance and overtime → HR repositories: coordinates
- Leave workflow → HR repositories: coordinates
- Payroll workflow → HR repositories: coordinates
- HR repositories → HR entities: persists
- HR repositories → Relational database: reads and writes
- Audit aspect and interceptor → Employee service: audits
- Audit aspect and interceptor → Leave workflow: audits
- Audit aspect and interceptor → Payroll workflow: audits