End-to-End Workflow

The platform is organized around a setup-to-submission-to-approval-to-finance pipeline.

1. Setup

Admin or client-scoped users configure the client and project operating environment:

• Clients and users in AdminPortalController.
• Client project setup in AdminClientManagementController and AdminClientProjectSetupController.
• Projects, project locations, supervisors, electricians, materials, cost codes, rates, allowances, ordinary-hours rules, work conditions, event rates, expense categories, and award matrix rules.
• Master configuration templates in ConfigTemplateSet and MasterConfigurationItem.

Setup data is client-owned unless it is a global master template.

2. Submission

Electricians submit timesheets and expenses through browser or mobile surfaces:

• Browser: Portal/ElectricianController.php
• API v2: Api/V2/ElectricianController.php
• Shared creation/update normalization: PortalTimesheetSubmissionHelper.php

A submitted timesheet contains entries with start/end times, codes, vehicle type, allowances, materials, work conditions, and optional location metadata.

3. Automatic side effects

After Doctrine persists the work:

• TimesheetAllowanceCalculationSubscriber refreshes calculated allowance lines for submitted, accepted, and approved timesheets.
• TimesheetAwardCalculationSubscriber queues award snapshot regeneration after flush.
• Notification listeners create inbox/push/email style notifications for assignment and submission events.
• Risk assessment subscribers/managers can score the timesheet.
• Change logger records field-level differences when edit services are used.

4. Supervisor review

Supervisors review submissions through:

• Browser: Portal/SupervisorController.php
• API v2: Api/V2/SupervisorController.php

They can accept or reject timesheets and expenses. Supervisor timesheet approval sheets group submissions for review and signature. A supervisor can edit job/cost code fields before sign-off according to TimesheetEditPolicy.

5. Payroll or Client Admin approval

Payroll and client admin flows move accepted work into approved or Xero-ready states. Payroll pages provide weekly employee review, pay summary, payslip/PDF views, bulk approval, rejection, and reports.

Key controller: Portal/PayrollController.php.

6. Finance and invoice generation

Finance reviews invoices, mock invoices, weekly reports, and timesheets through Portal/FinanceController.php. PayrollInvoiceService and InvoicePdfViewBuilder build invoice aggregates and PDF-ready rows.

When an award billTotal exists and is greater than zero, invoice logic can use it as the labour basis and add materials. Otherwise it falls back to hours x matching client base rate plus allowance total plus material total.

7. Xero submission

Xero interaction is handled by:

• XeroAuthController
• XeroClient
• XeroIntegrationService
• XeroBillSubmissionService
• SubmitExpensesTimesheetsToXeroCommand

Xero routes require an authenticated browser session. Environment defaults allow development/mock behavior through XERO_ENV and related credentials.