Incidents & Near Misses¶

Status: Specified — ready to build Build order: 7 of 10 — depends on Projects & Sites, Personnel & Attendance, Plant & Equipment

Purpose¶

Incidents & Near Misses is the reporting and investigation log for health, safety, and environmental events on site. It captures the initial report, classifies RIDDOR-reportable events, guides the reporter through mandatory details, and tracks the 10-day HSE reporting deadline. All incident records form the immutable audit trail required for legal and insurance purposes.

Entities¶

Incident¶

A single incident or near miss event.

CREATE UNIQUE INDEX idx_incident_reference
    ON incidents(reference) WHERE deleted_at IS NULL;
CREATE INDEX idx_incident_site_id
    ON incidents(site_id, occurred_at DESC) WHERE deleted_at IS NULL;
CREATE INDEX idx_incident_project_id
    ON incidents(project_id, occurred_at DESC) WHERE deleted_at IS NULL;
CREATE INDEX idx_incident_status
    ON incidents(project_id, status) WHERE deleted_at IS NULL;
-- RIDDOR deadline scanner
CREATE INDEX idx_incident_riddor_deadline
    ON incidents(riddor_deadline)
    WHERE riddor_reportable = true
      AND riddor_reported_to_hse = false
      AND deleted_at IS NULL;

Severity levels:

RIDDOR categories:

Incident status:

IncidentPhoto¶

Photos attached to an incident record.

CREATE INDEX idx_incident_photo_incident
    ON incident_photos(incident_id) WHERE deleted_at IS NULL;

Business Rules¶

1. reference is system-generated at creation time using a per-tenant sequence: INC-{current_year}-{sequence:04d}. Example: INC-2026-0047. The sequence resets each calendar year. Implemented in the service layer using SELECT MAX(sequence_number) + 1 FROM incidents WHERE EXTRACT(YEAR FROM created_at) = {year}.

2. When riddor_reportable is set to true:

3. riddor_category becomes required
4. riddor_deadline is computed as occurred_at + INTERVAL '10 days'

5. The incident.riddor_deadline notification is scheduled via the SQS queue for the scanner to pick up at 5 days and 2 days before deadline

6. riddor_reportable can be set at creation time or updated later (Site Managers may not initially recognise RIDDOR reportability). When updated to true on an existing record, riddor_deadline is computed from the original occurred_at.

7. Setting riddor_reported_to_hse = true requires riddor_reported_at and riddor_reference. This terminates the RIDDOR deadline notification.

8. involved_personnel is stored as a UUID array (PostgreSQL UUID[]). The API returns the full personnel summary (name, employment type) by joining on query. This denormalised array avoids a join table for a V1 feature.

9. involved_plant is similarly stored as a UUID array.

10. Closing an incident (status → closed) requires root_cause and corrective_actions to be non-empty. Enforced in service layer.

11. Closed incidents can be reopened (set back to under_investigation) by Project Manager and above.

12. Incident records are never hard deleted. The soft delete on the deleted_at column means records remain accessible in audit exports even after deletion.

13. The RIDDOR guidance text shown in the UI is static informational content — it does not replace professional legal advice. It guides the site manager on whether the incident is likely reportable.

RIDDOR Guidance (UI Display Text)¶

When a user reports an incident and selects severity lost_time, specified_injury, dangerous_occurrence, or fatality, the UI displays this guidance block before the riddor_reportable question:

RIDDOR — is this reportable?

Under the Reporting of Injuries, Diseases and Dangerous Occurrences Regulations 2013, certain workplace incidents must be reported to the HSE within 10 days of the incident.

This may be reportable if: - A worker has been absent for more than 7 consecutive days (not counting the day of the incident) — report within 15 days - A worker suffered a specified injury (fracture except fingers/thumbs/toes, amputation, crush, loss of sight, chemical/hot metal burn to eye, electric shock, hospitalised for over 24 hours, or any injury leading to unconsciousness) - A dangerous occurrence occurred (crane collapse, explosion, scaffold collapse, etc.)

Contact your H&S manager or check hse.gov.uk/riddor for the full list. This platform reminds you of the deadline but does not submit to HSE on your behalf — you must report via HSE's online portal or by phone.

This text is stored as a tenant_label with key guidance.riddor so tenants can customise it.

API Endpoints¶

Incidents¶

Photos¶

Project-level view¶

Request / Response Shapes¶

POST /sites/{siteId}/incidents¶

// Request
{
  "incident_type": "incident",
  "severity": "lost_time",
  "title": "Worker fell from scaffold — left ankle fracture",
  "description": "At approximately 14:20, Marcus Obi (direct worker) fell approx. 1.5m from a working platform on scaffold adjacent to Grid C. He was wearing a harness but the lanyard was not clipped. Immediate first aid applied on site; ambulance called, worker taken to Royal London Hospital.",
  "occurred_at": "2026-05-28T14:20:00Z",
  "location_description": "Scaffold — Grid C, Level 2, north elevation",
  "involved_personnel": ["uuid-marcus-obi"],
  "involved_plant": [],
  "immediate_action_taken": "First aid applied. Area cordoned off. Ambulance called. Next of kin notified. Scaffold platform inspected and declared safe.",
  "riddor_reportable": true,
  "riddor_category": "specified_injury_worker",
  "custom_fields": {}
}

// Response 201
{
  "id": "uuid-incident",
  "reference": "INC-2026-0047",
  "site_id": "uuid-site",
  "project_id": "uuid-project",
  "incident_type": "incident",
  "severity": "lost_time",
  "title": "Worker fell from scaffold — left ankle fracture",
  "description": "...",
  "occurred_at": "2026-05-28T14:20:00Z",
  "reported_at": "2026-05-28T16:55:00Z",
  "location_description": "Scaffold — Grid C, Level 2, north elevation",
  "involved_personnel": [
    {
      "personnel_id": "uuid-marcus-obi",
      "full_name": "Marcus Obi",
      "employment_type": "direct"
    }
  ],
  "involved_plant": [],
  "immediate_action_taken": "...",
  "riddor_reportable": true,
  "riddor_category": "specified_injury_worker",
  "riddor_reported_to_hse": false,
  "riddor_deadline": "2026-06-07T14:20:00Z",
  "riddor_days_remaining": 10,
  "status": "open",
  "photo_count": 0,
  "custom_fields": {},
  "created_at": "2026-05-28T16:55:00Z",
  "created_by_name": "James Fletcher"
}

POST /sites/{siteId}/incidents/{id}/mark-riddor-reported¶

// Request
{
  "riddor_reported_at": "2026-05-30T10:00:00Z",
  "riddor_reference": "OCC-2026-12345"
}

// Response 200
{
  "id": "uuid-incident",
  "riddor_reported_to_hse": true,
  "riddor_reported_at": "2026-05-30T10:00:00Z",
  "riddor_reference": "OCC-2026-12345",
  "riddor_days_remaining": null
}

POST /sites/{siteId}/incidents/{id}/transition¶

// Request (closing)
{
  "status": "closed",
  "root_cause": "Worker had not been briefed on the mandatory harness clipping procedure for this scaffold tier. The site induction did not cover this tier specifically.",
  "corrective_actions": "All workers on site re-briefed. Scaffold checklist updated to include mandatory lanyard clip points. SSIP audit scheduled."
}

// Response 200 — full incident object

// Response 422 — missing root cause
{
  "error": "investigation_incomplete",
  "message": "root_cause and corrective_actions are required before closing an incident."
}

Permission Matrix¶

Site Managers can edit incidents in open or under_investigation status but cannot close them, reopen them, or mark RIDDOR as reported — these are Project Manager actions.

Notifications Triggered¶

The daily scanner query:

SELECT *
FROM incidents
WHERE riddor_reportable = true
  AND riddor_reported_to_hse = false
  AND riddor_deadline IS NOT NULL
  AND riddor_deadline BETWEEN NOW() AND NOW() + INTERVAL ':advance_days days'
  AND deleted_at IS NULL

Default advance_days for RIDDOR: 5 days and 2 days (from notifications spec).

Once riddor_reported_to_hse = true is set, the scanner stops finding this record.

Offline Sync Scope¶

Offline incident creation: - Site Manager creates incident offline — queued in local SQLite - Photos stored in device storage - On reconnect: incident synced, photos uploaded - reference (INC-YYYY-NNNN) is assigned server-side on first sync — the record shows "Pending" until synced

Cross-Module Dependencies¶

Upstream¶

Downstream¶

None. Incidents is a terminal module.

Tests Required¶

Incident Reporting¶

• Report incident — valid → 201, reference auto-generated INC-{year}-XXXX
• Report RIDDOR incident — riddor_deadline set to occurred_at + 10 days
• Report RIDDOR without riddor_category → 422
• Reference sequence increments per tenant per year
• riddor_days_remaining computed correctly (positive, zero, negative)

Status Transitions¶

• Transition open → under_investigation → 200
• Transition under_investigation → closed with root_cause and corrective_actions → 200
• Transition to closed without root_cause → 422
• Transition closed → under_investigation (reopen) by Project Manager → 200
• Transition closed → under_investigation by Site Manager → 403

RIDDOR¶

• Mark RIDDOR reported — valid → 200, riddor_reported_to_hse = true
• Mark RIDDOR reported without riddor_reference → 422
• After marking reported, riddor_days_remaining = null
• Set riddor_reportable = true on existing record → riddor_deadline computed from original occurred_at

Photos¶

• Add photo → presigned PUT URL returned
• List photos — ordered by sort_order
• Soft delete photo

Cross-tenant isolation (mandatory)¶

• GET incident from another tenant's site → 404
• POST incident with site_id from another tenant → 404
• POST with involved_personnel UUIDs from another tenant → 422

Permission boundaries¶

• Site Manager cannot close incident → 403
• Site Manager cannot mark RIDDOR reported → 403
• Site Manager can edit open/investigating incident → 200
• Site Manager cannot edit closed incident → 422
• Viewer can view but not edit → 403

Default Tenant Labels¶

Foundation Dependencies¶