Automated Compliance Certificate Distribution

From v0.1.57, the platform automatically distributes compliance certificates to active tenants whenever a Gas Safety Certificate, EPC, or EICR is uploaded or renewed for a property. Agents no longer need to manually forward documents or notify tenants.

Supported Document Types

Document Type	Internal Key
Gas Safety Certificate	GasSafety
Energy Performance Certificate (EPC)	EPC
Electrical Installation Condition Report (EICR)	EICR

How It Works

1. An agent uploads a compliance document via the compliance.create mutation.
2. If the document includes a file URL, the platform dispatches a compliance/certificate.distribute event.
3. The distribution function runs in isolated steps:
   • Loads the compliance document, property details, and organisation branding
   • Finds all active tenancies for the property
   • Locates matching tenant portal tokens by property address
   • For each tenant: adds the document to their portal store and sends a notification email
   • Notifies the uploading agent via in-app notification and confirmation email
4. The compliance document is marked as issuedToTenant = true.
5. The full distribution is logged in the audit trail.

What Tenants Receive

• Portal document: The certificate is added to the tenant's portal under the compliance category and is available for download at any time.
• Email notification: A branded email is sent to each tenant containing:
  • The document type (e.g. "Gas Safety Certificate")
  • The property address
  • The certificate expiry date (if available)
  • A direct link to their tenant portal

Note: Emails reference UK legal obligations ("as required by UK law") for Gas Safety, EPC, and EICR documentation.

What Agents Receive

After distribution completes, the uploading agent receives:

• An in-app notification confirming distribution
• A confirmation email listing the number of recipients and their names

If no active tenants exist for the property, the agent is notified and no distribution occurs.

Edge Cases

Scenario	Behaviour
No active tenancies for the property	Agent is notified; distribution is skipped
Document has no file URL	Distribution event is not triggered
Email not configured for the organisation	Documents are still added to tenant portals; email step is skipped silently
Inngest dispatch fails on upload	Document creation still succeeds; distribution can be retried independently

Reliability & Compliance

• Concurrency: Limited to 3 concurrent distributions per organisation to prevent system overload.
• Retries: Up to 3 automatic retries on transient failures.
• Permanent failures: A NonRetriableError is raised immediately for missing documents or missing properties (no retry wasted).
• Non-blocking dispatch: The document upload flow is never interrupted by distribution failures.
• Audit trail: Every distribution — including skipped distributions — is recorded in the platform audit log.
• Batch tracking: Each distribution run is registered with the platform batches system under the compliance-cert-distribute batch ID.

Technical Reference

Inngest Event

Event name: compliance/certificate.distribute

Payload:

{
  complianceDocumentId: string; // ID of the compliance document
  orgId: string;                // Organisation ID
  uploadedByUserId?: string;    // ID of the uploading agent (optional)
}

Function Configuration

{
  id: "compliance-cert-distribute",
  retries: 3,
  concurrency: [{ key: "event.data.orgId", limit: 3 }]
}

Email Templates

Two email templates are used by this feature:

Template	Recipient	Purpose
complianceCertTenantEmail	Tenant	Notifies tenant of the new/updated certificate with portal link
complianceCertAgentConfirmEmail	Agent	Confirms distribution with full recipient list

Both templates are rendered using the platform's shared emailLayout and support agency branding (name and from-address).