Subcontractors¶

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

Purpose¶

Subcontractors is the company register for all firms working under the main contractor on a project. It tracks insurance policies and trade accreditations with expiry dates, triggers alerts before they lapse, and provides the subcontractor_id FK referenced by the Personnel module.

Entities¶

Subcontractor¶

A company working on a project. Registered at the project level.

CREATE INDEX idx_subcontractors_project_id
    ON subcontractors(project_id) WHERE deleted_at IS NULL;
CREATE INDEX idx_subcontractors_status
    ON subcontractors(project_id, status) WHERE deleted_at IS NULL;

SubcontractorInsurance¶

An insurance policy held by a subcontractor. One company typically has multiple policies (public liability, employers' liability, professional indemnity, etc.).

CREATE INDEX idx_subco_insurance_subcontractor
    ON subcontractor_insurance(subcontractor_id) WHERE deleted_at IS NULL;
CREATE INDEX idx_subco_insurance_project
    ON subcontractor_insurance(project_id) WHERE deleted_at IS NULL;
CREATE INDEX idx_subco_insurance_expiry
    ON subcontractor_insurance(expiry_date) WHERE deleted_at IS NULL;

Suggested insurance types:

SubcontractorAccreditation¶

A trade certification, industry scheme membership, or safety scheme held by the subcontractor company. Separate from individual worker licences.

CREATE INDEX idx_subco_accreditation_subcontractor
    ON subcontractor_accreditations(subcontractor_id) WHERE deleted_at IS NULL;
CREATE INDEX idx_subco_accreditation_project
    ON subcontractor_accreditations(project_id) WHERE deleted_at IS NULL;
CREATE INDEX idx_subco_accreditation_expiry
    ON subcontractor_accreditations(expiry_date)
    WHERE deleted_at IS NULL AND expiry_date IS NOT NULL;

Suggested accreditation types:

Status Lifecycle — Subcontractor¶

Business Rules¶

1. Subcontractors are registered at the project level. The same company can exist in multiple projects as separate records (different scope, different contact, different insurance requirements per project).

2. subcontractor.id is the FK used in the Personnel module. Archiving or suspending a subcontractor does not automatically affect their workers' sign-in status. Personnel must be managed separately.

3. Insurance policies always have an expiry date — this is enforced in the Pydantic schema (not nullable for SubcontractorInsurance).

4. Accreditations may not expire (expiry_date nullable). If expiry_date IS NULL, they are excluded from expiry scanning.

5. Computed fields on the list response:

6. has_expiring_insurance — any insurance policy expiring within the configured alert threshold
7. has_expired_insurance — any insurance policy with expiry_date < CURRENT_DATE
8. has_expiring_accreditation — same for accreditations

9. has_expired_accreditation — same for accreditations

10. A subcontractor with expired insurance is visually flagged in the UI but is not blocked from having workers on site. Enforcement is the project manager's responsibility. The notification system handles the alerts.

API Endpoints¶

Subcontractors¶

Insurance¶

Accreditations¶

Request / Response Shapes¶

POST /projects/{projectId}/subcontractors¶

// Request
{
  "name": "Acme Steel Ltd",
  "company_number": "12345678",
  "contact_name": "Emma Walsh",
  "contact_email": "e.walsh@acmesteel.co.uk",
  "contact_phone": "0121 555 0100",
  "scope_of_works": "Structural steelwork — Blocks A and B",
  "custom_fields": {}
}

// Response 201
{
  "id": "uuid-subco",
  "project_id": "uuid-project",
  "name": "Acme Steel Ltd",
  "company_number": "12345678",
  "contact_name": "Emma Walsh",
  "contact_email": "e.walsh@acmesteel.co.uk",
  "contact_phone": "0121 555 0100",
  "scope_of_works": "Structural steelwork — Blocks A and B",
  "status": "active",
  "worker_count": 0,
  "has_expired_insurance": false,
  "has_expiring_insurance": false,
  "has_expired_accreditation": false,
  "has_expiring_accreditation": false,
  "insurance_count": 0,
  "accreditation_count": 0,
  "custom_fields": {},
  "created_at": "2026-05-28T09:00:00Z",
  "updated_at": "2026-05-28T09:00:00Z"
}

GET /projects/{projectId}/subcontractors¶

Query params: status, has_expired_insurance (bool), has_expiring_insurance (bool), q (name search), sort (default name), limit, cursor

// Response 200
{
  "data": [
    {
      "id": "uuid-subco",
      "name": "Acme Steel Ltd",
      "contact_name": "Emma Walsh",
      "status": "active",
      "worker_count": 12,
      "has_expired_insurance": false,
      "has_expiring_insurance": true,
      "has_expired_accreditation": false,
      "has_expiring_accreditation": false,
      "next_insurance_expiry": "2026-06-15",
      "next_accreditation_expiry": null
    }
  ],
  "pagination": { "total": 8, "cursor": null, "has_more": false }
}

POST /projects/{projectId}/subcontractors/{id}/insurance¶

// Request
{
  "insurance_type": "Public Liability",
  "insurer": "Aviva",
  "policy_number": "POL-2026-000123",
  "cover_amount": 5000000.00,
  "expiry_date": "2026-12-31"
}

// Response 201
{
  "id": "uuid-ins",
  "subcontractor_id": "uuid-subco",
  "insurance_type": "Public Liability",
  "insurer": "Aviva",
  "policy_number": "POL-2026-000123",
  "cover_amount": 5000000.00,
  "expiry_date": "2026-12-31",
  "verified": false,
  "verified_by": null,
  "verified_at": null,
  "document_url": null,
  "days_until_expiry": 217,
  "status": "valid",
  "created_at": "2026-05-28T09:00:00Z"
}

Computed status on insurance and accreditation responses:

Permission Matrix¶

Site Managers can view subcontractor details and their linked workers (to know who they're managing on site) but cannot add or edit company-level records.

Notifications Triggered¶

Both scanners use the same pattern as the licence expiry scanner:

-- Insurance
SELECT si.*, s.project_id
FROM subcontractor_insurance si
JOIN subcontractors s ON s.id = si.subcontractor_id
WHERE si.deleted_at IS NULL
  AND si.expiry_date BETWEEN CURRENT_DATE AND CURRENT_DATE + :advance_days
  AND s.status = 'active'
  AND s.deleted_at IS NULL

-- Accreditations
SELECT sa.*, s.project_id
FROM subcontractor_accreditations sa
JOIN subcontractors s ON s.id = sa.subcontractor_id
WHERE sa.deleted_at IS NULL
  AND sa.expiry_date IS NOT NULL
  AND sa.expiry_date BETWEEN CURRENT_DATE AND CURRENT_DATE + :advance_days
  AND s.status = 'active'
  AND s.deleted_at IS NULL

Offline Sync Scope¶

Site Managers see the company name on the personnel register (denormalised from the FK join) but don't need the full insurance/accreditation dataset on device.

Cross-Module Dependencies¶

Upstream¶

Downstream¶

The Personnel module uses subcontractor_id as a FK. This module must be built before that FK constraint is enforced. The migration to add the FK runs when Subcontractors is built.

Tests Required¶

Subcontractor CRUD¶

• Register subcontractor — valid payload → 201
• List subcontractors — filter by status, has_expired_insurance
• Name search (q) matches on name and trading_name
• Transition status — valid transitions succeed
• Transition status — invalid → 409
• Soft delete — removed from list; linked personnel records unaffected
• worker_count derived correctly from personnel FK

Insurance¶

• Add policy — valid → 201
• Add policy — expiry_date in the past → accepted (expired)
• days_until_expiry and computed status correct for all states
• Verify — sets verified = true, records verified_by and verified_at
• Soft delete — excluded from subsequent queries

Accreditations¶

• Add — valid, no expiry → status = no_expiry
• Add — with expiry → status computed correctly
• Soft delete — excluded

Expiry flags on list response¶

• has_expiring_insurance true when at least one policy within alert threshold
• has_expired_insurance true when at least one policy past expiry
• Flags false when all policies are valid

Cross-tenant isolation (mandatory)¶

• GET subcontractor from another tenant → 404
• POST insurance with subcontractor_id from another tenant → 404
• Subcontractor from Project A cannot be FKed to workers in Project B

Permission boundaries¶

• Site Manager cannot create/edit subcontractor → 403
• Site Manager can list subcontractors and view detail → 200
• Viewer can list and view → 200; cannot edit → 403

Default Tenant Labels¶

Foundation Dependencies¶