HRM-System/docs/payroll_workflow.md

HRM Payroll Processing Workflow

Comprehensive architectural and operational guide to the payroll lifecycle.

Core Lifecycle Flow

1. Employee Onboarding -> 2. Shift Management -> 3. Attendance Tracking -> 4. Payroll Run (Cut-off) -> 5. Manual/Statutory Edits -> 6. Final Generation

graph TD
    A[Create Employee] -->|Validate Required Fields| B(Create Shift)
    B --> C(Assign Shift in Calendar)
    C --> D{Attendance Tracking}
    D -->|Manual Entry| E[Attendance Records]
    D -->|CSV/Excel Import| E
    D -->|Employee Clock In/Out| E
    E --> F[Create Payroll Run Cut-off]
    F --> G[Process Payroll Engine]
    G --> H{Requires Adjustments?}
    H -->|Yes| I[Edit Payroll Entry / Statutory Edits]
    I --> J
    H -->|No| J[Generate / Complete Payroll]

---

1. Employee Creation & Validation

Controller: EmployeeController@store

The process begins by onboarding an employee and ensuring all critical data is present.

• Required Fields: Name, Email, Password, Phone, DOB, Gender, Salary, Branch, Department, Designation, Date of Joining, Employment Type, Status, Full Address, Emergency Contact, and Bank Details.
• Document Validation: The system strictly enforces the upload of mandatory documents defined in DocumentType (e.g., ID, Contract).
• Outcome: Creates a User model linked to an Employee model.

2. Shift Creation

Controller: ShiftController@store

Before assigning attendance, valid shifts must be created.

• Parameters: Name, Start Time, End Time, Break Duration, Grace Period, and Night Shift toggle.
• Validation: Ensures no duplicate shift names exist per company.

3. Shift Assignment (Calendar)

Controller: ShiftController@assignShift

Shifts are assigned to employees over a specific date range (or marked as Rest Days).

• Process: The system iterates through the date range (CarbonPeriod) and uses AttendanceRecord::updateOrCreate to generate blank attendance records for the scheduled shifts.
• Default Status: Scheduled days are given a default status of present or absent (if it's a rest day) pending actual clock-ins.

4. Attendance Entry & Import

Controller: AttendanceRecordController

Attendance data populates the assigned shifts to reflect actual hours worked.

• Manual Entry (@store): HR administrators can manually input records, specifying clock_in, clock_out, and status (present, absent, half_day, on_leave, holiday).
• Import (@fileImport): Bulk attendance data can be imported via CSV/Excel. The system matches records by employee name and date, respecting the employee's assigned shift and attendance policy.
• Clock In/Out: Employees can log their own time, which updates the AttendanceRecord dynamically.
• Processing: processAttendance() is called to calculate total hours, late arrivals, and overtime.

5. Payroll Run & Processing (Cut-off)

Controller: PayrollRunController@store & @process Model: PayrollRun::processPayroll()

When the pay period concludes, a Payroll Run is generated.

• Initialization: Created in a draft status for a specific pay period (Start Date to End Date).
• Processing Engine: When "Process" is clicked, the system queries all active employees and passes them to the App\Services\PayrollService engine.
• Calculation: The engine evaluates the attendance records within the cut-off period against the employee's base salary to calculate:
  • Working days, Present days, Absences, and Leaves
  • Basic Salary and Component Earnings
  • Overtime Amount and Deductions (DOLE compliant)
• Outcome: Creates a PayrollEntry for each processed employee.

6. Statutory Edits & Adjustments

Controller: PayrollRunController@updateEntry

Before finalizing, HR/Payroll officers can review and adjust individual employee payroll entries.

• Adjustments: Users can modify basic_salary, component_earnings, overtime_amount, unpaid_leave_deduction, and total_deductions.
• Recalculation: The system automatically recalculates total_earnings, gross_pay, and net_pay (Gross Pay = Total Earnings, Net Pay = Gross Pay - Total Deductions).
• Top-Level Update: Updating an entry triggers PayrollRun->calculateTotals() to ensure the parent run reflects the new amounts.

7. Generation & Completion

Controller: PayrollRunController (Status Update)

Once all entries are verified and statutory edits are completed, the payroll run is finalized.

• Action: The status is updated from draft to completed.
• Finality: Once completed, the payroll entries are locked, and Payslips are ready for distribution and export.