# vvr-vikram/hrms-microservice architecture

> Architecture diagram of the GitHub repository vvr-vikram/hrms-microservice, 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-microservice
- Repository: https://github.com/vvr-vikram/hrms-microservice

## Overview

#### Purpose and topology
This is a Java 17+ Maven multi-module HRMS backend. Six Spring Boot applications form a REST microservice system: Eureka discovery, a gateway, and employee, attendance, leave, and payroll domains. Each business service owns a separate PostgreSQL database/schema boundary.

Key roots: `hrms-microservice/pom.xml`, `hrms-microservice/README.md`.

#### Startup and entry points
Start discovery first, then the gateway and business services. Each module is independently deployable as a Spring Boot JAR with its own configuration:
- Registry: `hrms-microservice/eureka-server/src/main/java/com/hrms/eureka/EurekaServerApplication.java`
- Edge gateway: `hrms-microservice/api-gateway/src/main/java/com/hrms/gateway/ApiGatewayApplication.java`
- Business entry points: `hrms-microservice/employee-service/src/main/java/com/hrms/employee/EmployeeServiceApplication.java`, `hrms-microservice/attendance-service/src/main/java/com/hrms/attendance/AttendanceServiceApplication.java`, `hrms-microservice/leave-service/src/main/java/com/hrms/leave/LeaveServiceApplication.java`

#### Service discovery and edge routing
Eureka (port 8761) is the registry and heartbeat endpoint; all five other applications register there. The API Gateway (port 8080) is the public REST boundary and routes gateway paths to discovered service instances: employees, attendance, leaves, and payroll.
- `hrms-microservice/eureka-server/src/main/resources/application.yml`
- `hrms-microservice/api-gateway/src/main/resources/application.yml`
- `hrms-microservice/api-gateway/pom.xml`

#### Employee system of record
Employee service (8081) owns employee records and audit logs. Requests flow controller → service/validation → JPA repositories, returning DTOs and translating failures through its global handler. Other domains consume employee-shaped DTOs rather than its persistence entities.
- `hrms-microservice/employee-service/src/main/java/com/hrms/employee/controller/EmployeeController.java`
- `hrms-microservice/employee-service/src/main/java/com/hrms/employee/service/EmployeeService.java`
- `hrms-microservice/employee-service/src/main/java/com/hrms/employee/entity/Employee.java`

#### Attendance and leave domains
Attendance service (8082) persists daily check-in/check-out records. Leave service (8083) manages leave applications, approval, and balances. Both expose REST controllers, retain local JPA repositories/entities, and include `RestTemplate` configuration plus employee DTOs, indicating synchronous employee-service integration at the service boundary.
- `hrms-microservice/attendance-service/src/main/java/com/hrms/attendance/service/AttendanceService.java`
- `hrms-microservice/attendance-service/src/main/java/com/hrms/attendance/entity/Attendance.java`
- `hrms-microservice/leave-service/src/main/java/com/hrms/leave/service/LeaveService.java`
- `hrms-microservice/leave-service/src/main/java/com/hrms/leave/entity/LeaveApplication.java`
- `hrms-microservice/leave-service/src/main/java/com/hrms/leave/entity/LeaveBalance.java`

#### Payroll orchestration
Payroll service (8084) owns payroll-slip persistence but depends on employee salary, attendance/workday, and leave/approval data. Payroll generation is therefore the principal cross-service flow: controller → payroll service → synchronous REST retrieval of employee, attendance, and leave DTOs → earnings/deduction/net calculation → local payroll persistence.
- `hrms-microservice/payroll-service/src/main/java/com/hrms/payroll/controller/PayrollController.java`
- `hrms-microservice/payroll-service/src/main/java/com/hrms/payroll/service/PayrollService.java`
- `hrms-microservice/payroll-service/src/main/java/com/hrms/payroll/entity/Payroll.java`

#### Runtime boundaries and infrastructure
All modules use Maven and Spring Boot; Spring Cloud supplies Eureka and gateway capabilities. PostgreSQL runs locally on configured port 5000, with distinct `hrms_employee_db`, `hrms_attendance_db`, `hrms_leave_db`, and `hrms_payroll_db` databases. Per-service `application.yml` files define runtime ports, discovery, security, datasource, and JPA behavior. Security configuration is present in every business service; exception handlers establish each service’s HTTP error boundary.

Main entry points: [`hrms-microservice/api-gateway/src/main/java/com/hrms/gateway/ApiGatewayApplication.java`](https://github.com/vvr-vikram/hrms-microservice/blob/master/hrms-microservice/api-gateway/src/main/java/com/hrms/gateway/ApiGatewayApplication.java) (API gateway), [`hrms-microservice/payroll-service/src/main/java/com/hrms/payroll/service/PayrollService.java`](https://github.com/vvr-vikram/hrms-microservice/blob/master/hrms-microservice/payroll-service/src/main/java/com/hrms/payroll/service/PayrollService.java) (Payroll service), [`hrms-microservice/leave-service/src/main/java/com/hrms/leave/service/LeaveService.java`](https://github.com/vvr-vikram/hrms-microservice/blob/master/hrms-microservice/leave-service/src/main/java/com/hrms/leave/service/LeaveService.java) (Leave service), [`hrms-microservice/employee-service/src/main/java/com/hrms/employee/service/EmployeeService.java`](https://github.com/vvr-vikram/hrms-microservice/blob/master/hrms-microservice/employee-service/src/main/java/com/hrms/employee/service/EmployeeService.java) (Employee service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_edge["Edge & Discovery"]
  node_registry{{"Eureka registry<br/>Spring Boot discovery"}}
  node_gateway{{"API gateway<br/>Spring Cloud gateway"}}
end

subgraph group_employee["Employee Domain"]
  node_employee_controller["Employee controller<br/>REST controller"]
  node_employee_service["Employee service<br/>domain service"]
  node_employee_entity["Employee records<br/>JPA entity<br/>[Employee.java]"]
  node_employee_db[("Employee PostgreSQL<br/>database")]
end

subgraph group_attendance["Attendance Domain"]
  node_attendance_service["Attendance service<br/>Spring Boot domain service"]
  node_attendance_entity["Attendance records<br/>JPA entity<br/>[Attendance.java]"]
  node_attendance_db[("Attendance PostgreSQL<br/>database")]
end

subgraph group_leave["Leave Domain"]
  node_leave_service["Leave service<br/>Spring Boot domain service<br/>[LeaveService.java]"]
  node_leave_application["Leave applications<br/>JPA entity"]
  node_leave_balance["Leave balances<br/>JPA entity<br/>[LeaveBalance.java]"]
  node_leave_db[("Leave PostgreSQL<br/>database")]
end

subgraph group_payroll["Payroll Domain"]
  node_payroll_controller["Payroll controller<br/>REST controller"]
  node_payroll_service["Payroll service<br/>orchestration service"]
  node_payroll_entity["Payroll slips<br/>JPA entity<br/>[Payroll.java]"]
  node_payroll_db[("Payroll PostgreSQL<br/>database")]
end

node_client(("REST clients<br/>external client"))

node_client -->|"public REST"| node_gateway
node_gateway -.->|"discovers routes"| node_registry
node_gateway -->|"routes employees"| node_employee_controller
node_gateway -->|"routes attendance"| node_attendance_service
node_gateway -->|"routes leaves"| node_leave_service
node_gateway -->|"routes payroll"| node_payroll_controller
node_employee_service -.->|"registers"| node_registry
node_attendance_service -.->|"registers"| node_registry
node_leave_service -.->|"registers"| node_registry
node_payroll_service -.->|"registers"| node_registry
node_employee_controller -->|"delegates"| node_employee_service
node_employee_service -->|"persists via JPA"| node_employee_entity
node_employee_entity -->|"stored in"| node_employee_db
node_attendance_service -->|"REST employee DTOs"| node_employee_service
node_attendance_service -->|"persists via JPA"| node_attendance_entity
node_attendance_entity -->|"stored in"| node_attendance_db
node_leave_service -->|"REST employee DTOs"| node_employee_service
node_leave_service -->|"persists via JPA"| node_leave_application
node_leave_service -->|"updates"| node_leave_balance
node_leave_application -->|"stored in"| node_leave_db
node_leave_balance -->|"stored in"| node_leave_db
node_payroll_controller -->|"generates payroll"| node_payroll_service
node_payroll_service -->|"REST salary DTOs"| node_employee_service
node_payroll_service -->|"REST workday DTOs"| node_attendance_service
node_payroll_service -->|"REST approval DTOs"| node_leave_service
node_payroll_service -->|"persists calculated slip"| node_payroll_entity
node_payroll_entity -->|"stored in"| node_payroll_db

click node_registry "https://github.com/vvr-vikram/hrms-microservice/blob/master/hrms-microservice/eureka-server/src/main/java/com/hrms/eureka/EurekaServerApplication.java"
click node_gateway "https://github.com/vvr-vikram/hrms-microservice/blob/master/hrms-microservice/api-gateway/src/main/java/com/hrms/gateway/ApiGatewayApplication.java"
click node_employee_controller "https://github.com/vvr-vikram/hrms-microservice/blob/master/hrms-microservice/employee-service/src/main/java/com/hrms/employee/controller/EmployeeController.java"
click node_employee_service "https://github.com/vvr-vikram/hrms-microservice/blob/master/hrms-microservice/employee-service/src/main/java/com/hrms/employee/service/EmployeeService.java"
click node_employee_entity "https://github.com/vvr-vikram/hrms-microservice/blob/master/hrms-microservice/employee-service/src/main/java/com/hrms/employee/entity/Employee.java"
click node_attendance_service "https://github.com/vvr-vikram/hrms-microservice/blob/master/hrms-microservice/attendance-service/src/main/java/com/hrms/attendance/service/AttendanceService.java"
click node_attendance_entity "https://github.com/vvr-vikram/hrms-microservice/blob/master/hrms-microservice/attendance-service/src/main/java/com/hrms/attendance/entity/Attendance.java"
click node_leave_service "https://github.com/vvr-vikram/hrms-microservice/blob/master/hrms-microservice/leave-service/src/main/java/com/hrms/leave/service/LeaveService.java"
click node_leave_application "https://github.com/vvr-vikram/hrms-microservice/blob/master/hrms-microservice/leave-service/src/main/java/com/hrms/leave/entity/LeaveApplication.java"
click node_leave_balance "https://github.com/vvr-vikram/hrms-microservice/blob/master/hrms-microservice/leave-service/src/main/java/com/hrms/leave/entity/LeaveBalance.java"
click node_payroll_controller "https://github.com/vvr-vikram/hrms-microservice/blob/master/hrms-microservice/payroll-service/src/main/java/com/hrms/payroll/controller/PayrollController.java"
click node_payroll_service "https://github.com/vvr-vikram/hrms-microservice/blob/master/hrms-microservice/payroll-service/src/main/java/com/hrms/payroll/service/PayrollService.java"
click node_payroll_entity "https://github.com/vvr-vikram/hrms-microservice/blob/master/hrms-microservice/payroll-service/src/main/java/com/hrms/payroll/entity/Payroll.java"

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_registry,node_gateway toneBlue
class node_employee_controller,node_employee_service,node_employee_entity,node_employee_db toneAmber
class node_attendance_service,node_attendance_entity,node_attendance_db toneMint
class node_leave_service,node_leave_application,node_leave_balance,node_leave_db toneRose
class node_payroll_controller,node_payroll_service,node_payroll_entity,node_payroll_db toneIndigo
class node_client toneNeutral
```

## Components

### Edge & Discovery

- [Eureka registry](https://github.com/vvr-vikram/hrms-microservice/blob/master/hrms-microservice/eureka-server/src/main/java/com/hrms/eureka/EurekaServerApplication.java): Spring Boot discovery · Service registry and heartbeat endpoint on port 8761. · `hrms-microservice/eureka-server/src/main/java/com/hrms/eureka/EurekaServerApplication.java`
- [API gateway](https://github.com/vvr-vikram/hrms-microservice/blob/master/hrms-microservice/api-gateway/src/main/java/com/hrms/gateway/ApiGatewayApplication.java): Spring Cloud gateway · Public REST boundary on port 8080. · `hrms-microservice/api-gateway/src/main/java/com/hrms/gateway/ApiGatewayApplication.java`

### Employee Domain

- [Employee controller](https://github.com/vvr-vikram/hrms-microservice/blob/master/hrms-microservice/employee-service/src/main/java/com/hrms/employee/controller/EmployeeController.java): REST controller · `hrms-microservice/employee-service/src/main/java/com/hrms/employee/controller/EmployeeController.java`
- [Employee service](https://github.com/vvr-vikram/hrms-microservice/blob/master/hrms-microservice/employee-service/src/main/java/com/hrms/employee/service/EmployeeService.java): domain service · Validates employee requests and returns DTOs. · `hrms-microservice/employee-service/src/main/java/com/hrms/employee/service/EmployeeService.java`
- [Employee records](https://github.com/vvr-vikram/hrms-microservice/blob/master/hrms-microservice/employee-service/src/main/java/com/hrms/employee/entity/Employee.java): JPA entity · Employee system-of-record model. · `hrms-microservice/employee-service/src/main/java/com/hrms/employee/entity/Employee.java`
- **Employee PostgreSQL**: database · hrms_employee_db; employee records and audit logs.

### Attendance Domain

- [Attendance service](https://github.com/vvr-vikram/hrms-microservice/blob/master/hrms-microservice/attendance-service/src/main/java/com/hrms/attendance/service/AttendanceService.java): Spring Boot domain service · Daily check-in/check-out REST domain on port 8082. · `hrms-microservice/attendance-service/src/main/java/com/hrms/attendance/service/AttendanceService.java`
- [Attendance records](https://github.com/vvr-vikram/hrms-microservice/blob/master/hrms-microservice/attendance-service/src/main/java/com/hrms/attendance/entity/Attendance.java): JPA entity · `hrms-microservice/attendance-service/src/main/java/com/hrms/attendance/entity/Attendance.java`
- **Attendance PostgreSQL**: database · hrms_attendance_db.

### Leave Domain

- [Leave service](https://github.com/vvr-vikram/hrms-microservice/blob/master/hrms-microservice/leave-service/src/main/java/com/hrms/leave/service/LeaveService.java): Spring Boot domain service · Leave application, approval, and balance domain on port 8083. · `hrms-microservice/leave-service/src/main/java/com/hrms/leave/service/LeaveService.java`
- [Leave applications](https://github.com/vvr-vikram/hrms-microservice/blob/master/hrms-microservice/leave-service/src/main/java/com/hrms/leave/entity/LeaveApplication.java): JPA entity · `hrms-microservice/leave-service/src/main/java/com/hrms/leave/entity/LeaveApplication.java`
- [Leave balances](https://github.com/vvr-vikram/hrms-microservice/blob/master/hrms-microservice/leave-service/src/main/java/com/hrms/leave/entity/LeaveBalance.java): JPA entity · `hrms-microservice/leave-service/src/main/java/com/hrms/leave/entity/LeaveBalance.java`
- **Leave PostgreSQL**: database · hrms_leave_db.

### Payroll Domain

- [Payroll controller](https://github.com/vvr-vikram/hrms-microservice/blob/master/hrms-microservice/payroll-service/src/main/java/com/hrms/payroll/controller/PayrollController.java): REST controller · `hrms-microservice/payroll-service/src/main/java/com/hrms/payroll/controller/PayrollController.java`
- [Payroll service](https://github.com/vvr-vikram/hrms-microservice/blob/master/hrms-microservice/payroll-service/src/main/java/com/hrms/payroll/service/PayrollService.java): orchestration service · Retrieves cross-service DTOs, calculates earnings, deductions, and net pay. · `hrms-microservice/payroll-service/src/main/java/com/hrms/payroll/service/PayrollService.java`
- [Payroll slips](https://github.com/vvr-vikram/hrms-microservice/blob/master/hrms-microservice/payroll-service/src/main/java/com/hrms/payroll/entity/Payroll.java): JPA entity · `hrms-microservice/payroll-service/src/main/java/com/hrms/payroll/entity/Payroll.java`
- **Payroll PostgreSQL**: database · hrms_payroll_db.

### Other components

- **REST clients**: external client

## Connections

- REST clients → API gateway: public REST
- API gateway → Eureka registry: discovers routes
- API gateway → Employee controller: routes employees
- API gateway → Attendance service: routes attendance
- API gateway → Leave service: routes leaves
- API gateway → Payroll controller: routes payroll
- Employee service → Eureka registry: registers
- Attendance service → Eureka registry: registers
- Leave service → Eureka registry: registers
- Payroll service → Eureka registry: registers
- Employee controller → Employee service: delegates
- Employee service → Employee records: persists via JPA
- Employee records → Employee PostgreSQL: stored in
- Attendance service → Employee service: REST employee DTOs
- Attendance service → Attendance records: persists via JPA
- Attendance records → Attendance PostgreSQL: stored in
- Leave service → Employee service: REST employee DTOs
- Leave service → Leave applications: persists via JPA
- Leave service → Leave balances: updates
- Leave applications → Leave PostgreSQL: stored in
- Leave balances → Leave PostgreSQL: stored in
- Payroll controller → Payroll service: generates payroll
- Payroll service → Employee service: REST salary DTOs
- Payroll service → Attendance service: REST workday DTOs
- Payroll service → Leave service: REST approval DTOs
- Payroll service → Payroll slips: persists calculated slip
- Payroll slips → Payroll PostgreSQL: stored in