Plant & Equipment¶

Status: Specified — ready to build Build order: 6 of 10 — depends on Projects & Sites

Purpose¶

Plant & Equipment is the asset register for all construction plant and equipment used on a project. It tracks LOLER and PUWER inspection certificates, hire return dates, and current site allocation. The notification system fires alerts before certificates lapse and when hire periods approach expiry. The module also triggers immediate alerts when plant with overdue inspection is allocated to an active site.

Entities¶

PlantItem¶

A single piece of plant or equipment on the project. Can be owned by the main contractor, hired from a plant hire company, or owned by a subcontractor.

CREATE INDEX idx_plant_project_id
    ON plant_items(project_id) WHERE deleted_at IS NULL;
CREATE INDEX idx_plant_allocated_site
    ON plant_items(allocated_site_id) WHERE deleted_at IS NULL AND allocated_site_id IS NOT NULL;
CREATE INDEX idx_plant_status
    ON plant_items(project_id, status) WHERE deleted_at IS NULL;
CREATE INDEX idx_plant_hire_end
    ON plant_items(hire_end_date)
    WHERE deleted_at IS NULL AND hire_end_date IS NOT NULL;

Suggested plant types:

plant_type is stored as VARCHAR — no central type table.

PlantInspection¶

An inspection or examination record for a piece of plant. Covers both LOLER thorough examinations and other periodic inspection types.

CREATE INDEX idx_plant_inspection_plant_id
    ON plant_inspections(plant_item_id) WHERE deleted_at IS NULL;
CREATE INDEX idx_plant_inspection_project
    ON plant_inspections(project_id) WHERE deleted_at IS NULL;
-- Expiry scanner
CREATE INDEX idx_plant_inspection_expiry
    ON plant_inspections(expiry_date)
    WHERE deleted_at IS NULL AND expiry_date IS NOT NULL;

Inspection types:

PlantAllocationLog¶

Immutable log of all site allocation changes. The current allocation is stored on plant_items.allocated_site_id for fast query. This table provides history.

CREATE INDEX idx_plant_alloc_plant
    ON plant_allocation_log(plant_item_id, actioned_at DESC);
CREATE INDEX idx_plant_alloc_site
    ON plant_allocation_log(site_id, actioned_at DESC);

Status Lifecycle — Plant¶

When transitioning to off_hire, any current site allocation is automatically cleared.

Business Rules¶

1. ownership_type = hired requires hire_company. Validated in service layer.

2. ownership_type = subcontractor_owned requires subcontractor_id.

3. LOLER check on allocation: when plant is allocated to a site (allocated_site_id set), the service checks whether any LOLER Thorough Examination is present and current (expiry_date >= CURRENT_DATE). If the most recent LOLER is expired (or no LOLER exists for a plant type that requires it), the plant.inspection_overdue_in_use notification is triggered. The allocation is not blocked — this mirrors sign-in behaviour for expired licences.

4. The LOLER check uses a lookup of whether the plant type requires LOLER. This is defined as a constant in the service layer based on the suggested types table. Custom plant types default to requiring LOLER (conservative).

5. hire_end_date drives the plant.hire_expiry notification. When a hired item's return date passes and status = active, the alert remains active until either the hire is extended (date updated) or the item is transitioned to off_hire.

6. A PlantInspection with result = fail flags the item with has_failed_inspection. The UI highlights it prominently. The plant is not automatically taken off-site but the flag is clearly visible.

7. The "current" inspection for any type is the most recent non-deleted record for that (plant_item_id, inspection_type). Only the current one drives expiry alerts.

API Endpoints¶

Plant¶

Site-level view¶

Inspections¶

Request / Response Shapes¶

POST /projects/{projectId}/plant¶

// Request
{
  "name": "360° Excavator — Liebherr R926",
  "plant_type": "Excavator (360°)",
  "make": "Liebherr",
  "model": "R926",
  "serial_number": "LIE-2019-044321",
  "ownership_type": "hired",
  "hire_company": "Sunbelt Rentals",
  "hire_reference": "HR-2026-0421",
  "hire_start_date": "2026-05-01",
  "hire_end_date": "2026-08-31",
  "custom_fields": {}
}

// Response 201
{
  "id": "uuid-plant",
  "project_id": "uuid-project",
  "name": "360° Excavator — Liebherr R926",
  "plant_type": "Excavator (360°)",
  "make": "Liebherr",
  "model": "R926",
  "serial_number": "LIE-2019-044321",
  "ownership_type": "hired",
  "hire_company": "Sunbelt Rentals",
  "hire_reference": "HR-2026-0421",
  "hire_start_date": "2026-05-01",
  "hire_end_date": "2026-08-31",
  "hire_days_remaining": 95,
  "allocated_site_id": null,
  "allocated_site_name": null,
  "status": "active",
  "has_valid_loler": false,
  "has_failed_inspection": false,
  "loler_expiry_date": null,
  "photo_url": null,
  "custom_fields": {},
  "created_at": "2026-05-28T09:00:00Z"
}

POST /projects/{projectId}/plant/{id}/allocate¶

// Request
{ "site_id": "uuid-site", "notes": "Deployed to north face earthworks" }

// Response 200
{
  "id": "uuid-plant",
  "allocated_site_id": "uuid-site",
  "allocated_site_name": "Canary Wharf — Site A",
  "allocated_at": "2026-05-28T07:00:00Z",
  "inspection_warning": null
}

// Response 200 — with LOLER warning
{
  "id": "uuid-plant",
  "allocated_site_id": "uuid-site",
  "allocated_site_name": "Canary Wharf — Site A",
  "allocated_at": "2026-05-28T07:00:00Z",
  "inspection_warning": {
    "inspection_type": "LOLER Thorough Examination",
    "last_expiry_date": "2026-03-01",
    "days_overdue": 88
  }
}

Allocation succeeds in both cases. The inspection_warning is informational only. The plant.inspection_overdue_in_use notification is also fired on the SQS queue.

POST /projects/{projectId}/plant/{id}/inspections¶

// Request
{
  "inspection_type": "LOLER Thorough Examination",
  "inspector_name": "LOLER Inspections Ltd",
  "inspector_company": "LOLER Inspections Ltd",
  "inspection_date": "2026-05-20",
  "expiry_date": "2027-05-20",
  "result": "pass",
  "reference_number": "LOLER-2026-04421"
}

// Response 201
{
  "id": "uuid-inspection",
  "plant_item_id": "uuid-plant",
  "inspection_type": "LOLER Thorough Examination",
  "inspector_name": "LOLER Inspections Ltd",
  "inspection_date": "2026-05-20",
  "expiry_date": "2027-05-20",
  "result": "pass",
  "reference_number": "LOLER-2026-04421",
  "certificate_url": null,
  "days_until_expiry": 357,
  "status": "valid",
  "created_at": "2026-05-28T09:00:00Z"
}

Computed status on inspection responses:

Permission Matrix¶

Site Managers can record inspections (they're typically the ones on site when the inspection happens) but cannot delete records or remove plant from the project.

Notifications Triggered¶

Inspection expiry scanner query:

SELECT pi.*, p.project_id
FROM plant_inspections pi
JOIN plant_items p ON p.id = pi.plant_item_id
WHERE pi.deleted_at IS NULL
  AND pi.expiry_date IS NOT NULL
  AND pi.expiry_date BETWEEN CURRENT_DATE AND CURRENT_DATE + :advance_days
  AND p.status = 'active'
  AND p.deleted_at IS NULL
  -- Only the most recent inspection of each type per item
  AND pi.id = (
    SELECT id FROM plant_inspections pi2
    WHERE pi2.plant_item_id = pi.plant_item_id
      AND pi2.inspection_type = pi.inspection_type
      AND pi2.deleted_at IS NULL
    ORDER BY pi2.inspection_date DESC LIMIT 1
  )

Hire expiry scanner query:

SELECT *
FROM plant_items
WHERE deleted_at IS NULL
  AND ownership_type = 'hired'
  AND hire_end_date IS NOT NULL
  AND hire_end_date BETWEEN CURRENT_DATE AND CURRENT_DATE + :advance_days
  AND status = 'active'

Offline Sync Scope¶

Site Manager sync includes all plant allocated to their sites. Useful for pre-use checks and certificate lookup on site without a data connection.

Cross-Module Dependencies¶

Upstream¶

Downstream¶

Tests Required¶

Plant CRUD¶

• Add plant — ownership_type = hired without hire_company → 422
• Add plant — ownership_type = subcontractor_owned without subcontractor_id → 422
• List plant — filter by status, ownership_type, allocated_site_id
• hire_days_remaining computed correctly — positive and negative values
• has_valid_loler and loler_expiry_date derived from inspections
• Transition status — off_hire clears allocated_site_id

Allocation¶

• Allocate — valid plant to site → 200, log entry created
• Allocate — plant with expired LOLER → 200 with inspection_warning, notification queued
• Allocate — plant already on same site → 409
• Allocate — plant already on different site → automatically returns from old site first
• Return — clears allocated_site_id, log entry created

Inspections¶

• Add inspection — valid → 201
• Add inspection — result = pass_with_defects without defects_noted → 422
• Computed status correct for all values including failed
• LOLER check: has_valid_loler updates when new LOLER inspection added

Notification triggers¶

• Allocate plant with expired LOLER → plant.inspection_overdue_in_use pushed to SQS
• Same plant, same site, same day → second push suppressed (idempotency)

Cross-tenant isolation (mandatory)¶

• GET plant from another tenant's project → 404
• POST inspection with plant_item_id from another tenant → 404
• Allocate to site_id from another tenant → 404

Permission boundaries¶

• Site Manager cannot add plant → 403
• Site Manager can allocate plant to own site → 200
• Site Manager cannot delete inspection → 403
• Viewer can view plant and inspections → 200; cannot edit → 403

Default Tenant Labels¶

Foundation Dependencies¶