Compliance & Works Management

The compliance module provides a central data layer for managing regulatory certificates, contractor records, maintenance works orders, and site inspections across your block portfolio.

Overview

Four entities make up the compliance module:

Entity	Purpose
Contractors	Org-wide directory of contractors with trade, accreditation, and insurance details
Compliance Certificates	Per-block register of all compliance and regulatory certificates
Maintenance Works	Works orders tracking reactive and planned maintenance with a status workflow
Inspections	Scheduled and ad-hoc site inspections with completion reporting

All entities are scoped to your organisation. Certificates and works orders are additionally scoped to a specific block.

Contractors

The contractor directory is shared across your entire portfolio. A contractor record stores the information needed to vet and assign a contractor to works or certificates.

Fields

Field	Description
`companyName`	Company or trading name (required)
`trade`	Primary trade category (required)
`additionalTrades`	Secondary trade categories (JSON array string)
`contactName`	Primary contact person
`email`	Primary email address
`phone`	Primary phone number
`addressLine1`, `addressLine2`, `city`, `postcode`	Postal address
`website`	Website URL
`gasSafeNumber`	Gas Safe Register number
`niceicNumber`	NICEIC registration number
`accreditations`	Other registration numbers (JSON string)
`publicLiabilityInsuranceExpiry`	Public liability expiry date
`publicLiabilityInsurancePolicyNumber`	Public liability policy number
`professionalIndemnityInsuranceExpiry`	Professional indemnity expiry date
`professionalIndemnityInsurancePolicyNumber`	Professional indemnity policy number
`employersLiabilityInsuranceExpiry`	Employers' liability expiry date
`employersLiabilityInsurancePolicyNumber`	Employers' liability policy number
`isActive`	Whether the contractor is available for new works (default: `true`)
`rating`	Internal rating, 1–5 (optional)
`notes`	Free-text internal notes

Trade Categories

plumbing · electrical · gas · fire_safety · lift_engineering · roofing · painting_decorating · cleaning · landscaping · locksmith · pest_control · general_building · surveying · asbestos · damp_proofing · scaffolding · security · glazing · carpentry · other

Permissions

List / read: any org member
Create / update / delete: admin role required

Compliance Certificates

Each block has its own certificate register. Certificates track the status of all regulatory and compliance documents required for the block.

Certificate Types

Type	Common Renewal Period
`gas_safety`	Annual (CP12)
`electrical_eicr`	Every 5 years
`fire_risk_assessment`	Reviewed annually
`ews1`	As required (cladding)
`asbestos_survey`	Reviewed every 12 months
`legionella`	Reviewed every 2 years
`lift_inspection`	Every 6 months (LOLER)
`epc`	Every 10 years
`pat_testing`	Annual
`lightning_protection`	Annual
`water_hygiene`	Periodic
`emergency_lighting`	Annual
`dry_riser`	Every 6 months
`other`	As required

Status (RAG)

Status	Meaning
`valid`	Current; not due to expire within 30 days
`expiring_soon`	Expires within 30 days
`expired`	Past expiry date
`not_applicable`	Not required for this block

Key Fields

Field	Description
`blockId`	The block this certificate belongs to
`certificateType`	One of the 14 types above
`status`	RAG status
`issuedDate`	Date the certificate was issued (required)
`expiryDate`	Certificate expiry date
`nextReviewDate`	Next review date (may differ from expiry)
`issuer`	Issuing body or engineer name
`contractorId`	Linked contractor who issued the certificate
`fileUrl`	Direct URL to the certificate file
`documentId`	Document vault reference for version-controlled storage
`responsiblePerson`	Name of person responsible for renewal
`responsibleUserId`	Platform user ID of the responsible person
`reference`	Certificate reference number or description

Permissions

List / read: any org member
Create / update / delete: admin role required

Maintenance Works Orders

Works orders track reactive and planned maintenance tasks from initial request through to completion.

Status Workflow

draft → approved → in_progress → complete
                              → cancelled

When a works order transitions to approved, the approvedBy (user ID) and approvedAt (timestamp) fields are automatically set.

Priority Levels

Priority	Typical Response
`emergency`	Immediate (e.g. gas leak, flood)
`urgent`	Within 24 hours (e.g. broken entry system)
`routine`	Within 7 days (e.g. communal light replacement)
`planned`	Scheduled maintenance (e.g. annual gutter clear)

Key Fields

Field	Description
`blockId`	The block this works order is for
`title`	Human-readable title (required)
`description`	Detailed scope of work
`status`	Current workflow status
`priority`	Priority level
`contractorId`	Assigned contractor
`costEstimatePence`	Estimated cost in pence
`actualCostPence`	Actual cost in pence (on completion)
`invoiceReference`	Purchase order or invoice reference
`raisedDate`	Date the order was raised (required)
`scheduledDate`	Planned start date
`completionDate`	Date works were completed
`certificateId`	Linked compliance certificate (for certificate-driven works)
`unitId`	Specific unit, if works are unit-scoped
`raisedBy`	User ID of the person who raised the order (auto-set)
`approvedBy`	User ID of approver (auto-set on approval)
`approvedAt`	Approval timestamp (auto-set on approval)

Permissions

List / read: any org member
Create / update / delete: admin role required

Inspections

Inspections record scheduled and completed site visits. They can be recurring (with a defined frequency) or ad-hoc.

Inspection Types

general_site · fire_safety · health_safety · lift · roof · drainage · communal_areas · external_fabric · grounds · move_in_out · other

Move-in/move-out inspections can be scoped to a specific unit via the unitId field.

Status

scheduled → completed
          → overdue
          → cancelled

When an inspection is updated to completed and no lastCompletedDate is provided, it is automatically set to the current timestamp.

Frequencies

weekly · fortnightly · monthly · quarterly · half_yearly · annually · ad_hoc

Default frequency is quarterly.

Key Fields

Field	Description
`blockId`	The block being inspected
`inspectionType`	Type of inspection
`title`	Human-readable title (required)
`description`	Scope or notes
`frequency`	Recurrence schedule
`nextDueDate`	When the next inspection is due
`scheduledDate`	Date of the scheduled inspection
`lastCompletedDate`	Date last completed (auto-set on completion)
`inspectorName`	Name of the inspector
`inspectorUserId`	Platform user ID of the inspector
`findingsHtml`	Inspection report / findings (HTML)
`conditionRating`	Overall condition rating, 1–5
`defectsFound`	Whether defects were identified
`defectCount`	Number of defects identified
`unitId`	Specific unit (for move-in/move-out inspections)

Permissions

List / read: any org member
Create / update / delete: admin role required

Audit Logging

Every create, update, and delete action across all four compliance entities is written to the audit log. This satisfies the pinned spec requirement: "Compliance Audit Trail — All Compliance Actions Logged".

Logged actions:

contractor.created
contractor.updated
contractor.deleted
compliance_certificate.created
compliance_certificate.updated
compliance_certificate.deleted
maintenance_works.created
maintenance_works.updated
maintenance_works.deleted
inspection.created
inspection.updated
inspection.deleted

The audit log entry includes the orgId, userId, resourceType, resourceId, and contextual metadata (e.g. block ID, certificate type, previous status on works updates).

Data Relationships

blocks
  ├── compliance_certificates (many)
  │     └── contractors (one, optional — issuer)
  │     └── documents   (one, optional — vault reference)
  ├── maintenance_works (many)
  │     ├── contractors           (one, optional — assigned)
  │     ├── compliance_certificates (one, optional — linked cert)
  │     └── units                 (one, optional — unit scope)
  └── inspections (many)
        └── units (one, optional — unit scope)

contractors
  ├── compliance_certificates (many — as issuer)
  └── maintenance_works       (many — as assigned contractor)

Multi-Tenant Isolation

All four tables (contractors, compliance_certificates, maintenance_works, inspections) are covered by row-level security (RLS), enforcing strict data isolation between organisations at the database level. All router procedures additionally filter by orgId from the authenticated session. Block-scoped operations validate that the target block belongs to the caller's organisation before any write is performed.