Employee Management Module

Overview

The Employee Management module is the foundational module of the HRMS. Every other module (KPI, Probation, Leave, Attendance) builds on top of employee records.

Scope

Feature	Status
Employee CRUD	✅ Implemented
Profile Picture	✅ Implemented
Attachments	✅ Implemented
Reporting Hierarchy	✅ Implemented
CSV Import	✅ Implemented
CSV Export	✅ Implemented
Bulk Actions	🔜 Planned

Data Model

Core Tables

employees (id, employee_number, first_name, last_name, ...)
├── has one    → user (id, name, email, password)
├── belongs to → entity (company)
├── belongs to → department
├── belongs to → employee (reports_to)
├── has many   → emergency_contacts
├── has many   → dependents
├── has many   → qualifications (polymorphic: work_experiences, education, skills, languages, licenses)
├── has many   → attachments (polymorphic, categorized by section)
└── has many   → kpi_evaluations

Key Relationships

Relationship	Type	Description
Employee → User	One-to-One	Every employee has a linked system user account
Employee → Entity	Many-to-One	Employee belongs to one company
Employee → Department	Many-to-One	Employee belongs to one department
Employee → Employee (Reports To)	Self-referencing	Creates management chain
Department → Managers	Many-to-Many	Via department_manager pivot
Department → Team Leads	Many-to-Many	Via department_team_lead pivot

Business Rules

Activity Status + Lifecycle Validation

Activity Status	Allowed Lifecycles
Active	Probationary, Confirmed
Inactive	Resigned, Terminated

Invalid combinations (e.g., Active + Terminated) are rejected at the request validation layer.

Employee Number

• Automatically generated when an employee is created
• Format: ENTITYNAME-NNN (e.g., HAYO-001, SLICK-002)
• The prefix is derived from the entity name (uppercased, non-alphanumeric characters removed)
• The sequence number is zero-padded to 3 digits and increments per entity
• Uses database-level locking (lockForUpdate) to prevent race conditions
• Cannot be changed after creation (enforced by prohibited validation rule)
• During CSV import, the column is optional — auto-generated if blank or missing

Work Email

• Must be unique across the entire system
• Used as the login email for the linked user account

Deletion Policy

Employee records are never deleted. They are deactivated by setting activity_status = Inactive and updating the lifecycle to Resigned or Terminated.

Architecture

Backend Components

Component	Path	Purpose
Model	app/Models/Employee.php	Eloquent model with relationships and scopes
Controller	app/Http/Controllers/EmployeeController.php	CRUD endpoints
Number Generator	app/Services/EmployeeNumberGenerator.php	Auto-generates employee numbers per entity
Service	app/Services/EmployeeService.php	Business logic
Import Service	app/Services/EmployeeImportService.php	CSV import processing
Policy	app/Policies/EmployeePolicy.php	Authorization rules
Resource	app/Http/Resources/EmployeeResource.php	API response transformation
Requests	app/Http/Requests/Employee/	Validation rules per action

Frontend Components

Component	Path	Purpose
List Page	app/dashboard/employees/page.tsx	Employee listing with search, filter, export
Create Page	app/dashboard/employees/create/page.tsx	Multi-tab creation wizard
Detail Page	app/dashboard/employees/[id]/page.tsx	Employee profile view
Edit Page	app/dashboard/employees/[id]/edit/page.tsx	Multi-tab edit form

Visibility Scoping

Employee visibility is controlled by the EmployeePolicy based on the user's role:

// Simplified visibility logic
Admin / HR    → all employees
Manager       → all employees (read-only)
TeamLead      → employees in led departments + own record
Employee      → own record only

API Endpoints

Method	Endpoint	Description
GET	/api/employees	List employees (paginated, filterable)
POST	/api/employees	Create employee
GET	/api/employees/{id}	Get employee details
PUT	/api/employees/{id}	Update employee
POST	/api/employees/{id}/profile-picture	Upload profile picture
DELETE	/api/employees/{id}/profile-picture	Remove profile picture
GET	/api/employees/{id}/attachments	List attachments
POST	/api/employees/{id}/attachments	Upload attachment
DELETE	/api/employees/{id}/attachments/{aid}	Delete attachment
GET	/api/employees/export/csv	Export CSV
POST	/api/employees/import	Import from CSV

2026-03 UX Updates

• Employee personal details UI now uses Salutation + First Name + Last Name order in create/edit form.
• Salutation is persisted in the existing middle_name field for backward-compatible storage (no schema migration).
• Employee attachments now provide Preview for supported files (images/PDF) plus download.