Appointed Roles¶

Status: Specified — ready to build Build order: 12 of 13 — depends on Projects & Sites, Personnel

Purpose¶

Appointed Roles is the project-level register of formal safety role appointments. UK H&S legislation and construction contract requirements mandate that specific roles are held by named, qualified individuals on every project and site — Fire Marshal, First Aider, COSHH Coordinator, Lifting Appointed Person, and others. This module tracks who holds each appointment, their qualification status, and the formal appointment letter on record.

The register surfaces gaps: roles with no appointee, nominations awaiting approval, and roles where the appointed person's qualification is expiring.

Entities¶

RoleDefinition¶

A standard safety role that can be appointed on a project. Platform provides a default set; tenants can add custom roles.

CREATE INDEX idx_role_definition_project
    ON role_definitions(project_id) WHERE deleted_at IS NULL;

Platform standard roles:

RoleAppointment¶

The record of a person holding (or being nominated for) a specific role on a project or site.

CREATE INDEX idx_role_appointment_project
    ON role_appointments(project_id) WHERE deleted_at IS NULL;
CREATE INDEX idx_role_appointment_site
    ON role_appointments(site_id) WHERE deleted_at IS NULL AND site_id IS NOT NULL;
CREATE INDEX idx_role_appointment_personnel
    ON role_appointments(personnel_id) WHERE deleted_at IS NULL;
CREATE INDEX idx_role_appointment_status
    ON role_appointments(project_id, status) WHERE deleted_at IS NULL;
-- Expiry scanner
CREATE INDEX idx_role_appointment_expiry
    ON role_appointments(expiry_date) WHERE deleted_at IS NULL AND expiry_date IS NOT NULL;

Appointment status values:

Business Rules¶

1. Multiple people can hold the same role on a project. There is no uniqueness constraint on (project_id, role_definition_id) — a project may have three First Aiders.

2. A site_id scopes the appointment to a specific site. A project-wide appointment (site_id = NULL) covers all sites on the project. Both can coexist — a project-wide Lifting AP and a site-specific Lifting AP are separate records.

3. Transitioning status to appointed does not require an appointment_letter_key — for smaller projects, verbal confirmation may be recorded in notes. The letter upload is encouraged but not enforced by the API.

4. The list endpoint surfaces a "gap" view: for each standard role, it shows whether the project has at least one appointed holder. Roles with no appointed holder are flagged in the response.

5. Platform standard role definitions (project_id = NULL) cannot be edited or deleted. Tenants can create additional project-level roles.

6. expiry_date on an appointment reflects when the appointment itself expires (not the person's underlying qualification). The expiry scanner generates a notification when an appointment is approaching expiry.

API Endpoints¶

Role Definitions¶

Appointments¶

Request / Response Shapes¶

POST /projects/{projectId}/appointed-roles¶

// Request
{
  "site_id": null,
  "role_definition_id": "uuid-role-def",
  "personnel_id": "uuid-person",
  "status": "appointed",
  "effective_date": "2026-05-28",
  "expiry_date": null,
  "notes": "CPCS A61 card verified — copy on file."
}

// Response 201
{
  "id": "uuid-appointment",
  "project_id": "uuid-project",
  "site_id": null,
  "role": {
    "id": "uuid-role-def",
    "name": "Lifting Appointed Person (AP)",
    "requires_qualification": true
  },
  "personnel": {
    "id": "uuid-person",
    "full_name": "James Fletcher",
    "job_title": "Crane Supervisor"
  },
  "status": "appointed",
  "effective_date": "2026-05-28",
  "expiry_date": null,
  "appointment_letter_key": null,
  "notes": "CPCS A61 card verified — copy on file.",
  "created_at": "2026-05-28T09:00:00Z"
}

GET /projects/{projectId}/appointed-roles¶

Query params: site_id (NULL for project-wide, UUID for site-specific, all for both), status, role_definition_id, personnel_id, show_gaps (default true), limit, cursor

// Response 200
{
  "appointments": [
    {
      "id": "uuid-appointment",
      "role": { "id": "uuid-role-def", "name": "First Aider" },
      "personnel": { "id": "uuid-person", "full_name": "Sarah Ahmed" },
      "status": "appointed",
      "site_id": null,
      "effective_date": "2026-05-01",
      "expiry_date": null
    }
  ],
  "gaps": [
    {
      "role_definition_id": "uuid-role-def-2",
      "role_name": "Fire Marshal",
      "has_appointed": false,
      "nominations": 1
    }
  ],
  "pagination": { "total": 8, "cursor": null, "has_more": false }
}

Permission Matrix¶

Notifications Triggered¶

Scanner query:

SELECT *
FROM role_appointments
WHERE deleted_at IS NULL
  AND expiry_date IS NOT NULL
  AND expiry_date BETWEEN CURRENT_DATE AND CURRENT_DATE + :advance_days
  AND status = 'appointed'

Offline Sync Scope¶

Offline reads are sufficient — appointments are not created or edited on site in normal workflow.

Cross-Module Dependencies¶

Upstream¶

Downstream¶

None. Appointed Roles is a terminal module.

Tests Required¶

Role Definitions¶

• List includes platform standard roles + project-specific roles
• Create project-specific role → 201
• Cannot delete platform standard role → 403

Appointments¶

• Create appointment — valid → 201
• Create appointment — multiple people in same role → 201 (allowed)
• Create project-wide appointment (site_id = null) → 201
• Create site-scoped appointment → 201
• Transition status nominated → appointed → 200
• Upload appointment letter — returns presigned PUT URL
• List with show_gaps=true — gaps array populated for roles with no appointed holder
• Expiry scanner — appointment with expiry_date in advance window → notification

Cross-tenant isolation (mandatory)¶

• GET appointments from another tenant's project → 404
• POST appointment with personnel_id from another tenant → 404

Permission boundaries¶

• Site Manager cannot create or edit appointment → 403
• Project Manager can create appointment → 201
• Viewer can view register → 200

Default Tenant Labels¶

Foundation Dependencies¶