# 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**

```mermaid
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.