Configuration Model

How clients, projects, rates, allowances, materials, categories, and work conditions configure the platform.

Configuration hierarchy

The platform has a clear hierarchy:

Master configuration templates
  -> client-scoped configuration rows
    -> project-level enablement and overrides
      -> timesheet and time-entry selections
        -> calculated snapshots and invoice records

The important design rule is that master configuration is a template source. The calculators read client/project/time-entry records, not global template rows directly.

MasterConfigurationItem and the seed command provide reusable values that admins can import into a client. Examples include master expense categories, event rates, and other catalog items shown in the admin configuration screens.

Once imported, client-specific rows carry the operational meaning:

Client row	Used by
`ClientRate` and `ClientRateClass`	Award calculator and invoice fallback labor rates.
`ClientAllowance`	Allowance matrix and award allowance line generation.
`ClientEventRate`	Award overtime, weekend, public holiday, and other event-rate multipliers.
`ClientMaterial`	Timesheet material normalization and invoice material totals.
`ClientCostCode`	Project/timesheet coding and review workflows.
`ClientExpenseCategory` and `ProjectExpenseCategory`	Expense submission and project-specific reimbursement options.
`ClientWorkCondition`	Time-entry flags that can trigger allowance rules.
`ClientBreakRule`, `ClientShiftRule`, `ClientTravelRule`, `ClientCalloutRule`, `ClientOrdinaryHoursRule`	Award matrix extensions used when the corresponding feature flags are enabled.

Client and membership scope

Client is the commercial account. Users are connected to clients through memberships and project assignments:

ClientMembership stores client membership roles such as client admin, supervisor, electrician, finance, and payroll.
Project.teamData stores project team metadata, including user id, display name, EW class, and position.
Portal scope services use the authenticated user's memberships and role to restrict project, timesheet, expense, and invoice access.

This means the same person can have more than one relationship with the system, but every operational query should resolve to a client and project scope before showing data.

Project setup

Project is where client configuration becomes operational. A project can carry:

client relationship
locations and depot metadata
project team data
cost code options
material options
expense category options
allowance rows in allowances_data

Project allowance rows are especially important. They can enable or disable a client allowance for the project, override the rate, and choose a project-specific amount unit for project-variable allowances.

Timesheet payload configuration

TimeEntry and Timesheet.location contain operational selections captured from portals or mobile APIs:

Payload	Purpose
`TimeEntry.allowancesData`	Manual or selectable allowance choices made on the entry.
`TimeEntry.workConditionsData`	Flags such as dirty work or other client work conditions.
`TimeEntry.materialsData`	Selected material rows that later become invoice material totals.
`TimeEntry.vehicleType`	Vehicle type used by vehicle-triggered allowances.
`Timesheet.location`	Location coordinates, distance metadata, device capture time, materials fallback, and allowance fallback data.

Configuration safety rule

If a value affects payroll, invoicing, or Xero output, do not treat display labels as the only source of truth. Prefer stable ids when available, store snapshots at calculation time, and keep current calculation records immutable enough to explain what happened later.