Award Matrix Overview

The award matrix is the broader payroll/billing rules engine. It is implemented as a calculation snapshot layer beside live payroll and invoice workflows.

Main files:

• AwardTimesheetCalculator.php
• AwardTimesheetCalculationManager.php
• TimesheetAwardCalculationSubscriber.php
• TimesheetCalculation.php
• TimesheetCalculationLine.php

Calculation flow

AwardTimesheetCalculator::calculate() builds a new TimesheetCalculation from a timesheet:

1. Resolve ordinary-hours rule.
2. Resolve employee classification.
3. Resolve rate matrix.
4. Resolve event rates.
5. Build break preview.
6. Split ordinary vs overtime hours.
7. Calculate minimum shift top-up.
8. Split overtime into buckets.
9. Build special day preview lines.
10. Build shift loading lines.
11. Build travel lines.
12. Build callout lines.
13. Add ordinary, minimum shift, overtime, special day, shift loading, travel, callout, allowance, and expense/billing lines as applicable.
14. Store source snapshots and totals.

Snapshot manager

AwardTimesheetCalculationManager::recalculate() supersedes existing draft/current calculations, creates a new calculation from the calculator, sets it to current, attaches it to the timesheet, and persists it.

Subscriber lifecycle

TimesheetAwardCalculationSubscriber listens on flush and post-flush. It queues timesheets when changes include:

• Timesheet
• TimeEntry
• TimesheetAllowanceLine
• ClientAllowance

Then after flush, it recalculates submitted, accepted, and approved timesheets. This post-flush pattern avoids trying to persist a full new calculation inside the same flush cycle.