Tenancy Auto-End Sweep

The Tenancy Auto-End Sweep is a nightly batch workflow that automatically transitions active tenancies to ended status once their end date has passed. It ensures your tenancy records stay accurate without requiring manual intervention, and kicks off the post-tenancy compliance and inspection workflow automatically.

---

How It Works

Every night at 01:00 UTC, the system runs a sweep over all tenancies. Any tenancy that meets all of the following conditions is processed:

• status is active
• endDate is set (not null)
• endDate is earlier than today's date

For each matching tenancy, three things happen automatically:

1. Status Transition

The tenancy's status field is updated from active to ended. This change is written to the tenancies entity and reflected immediately across any views or reports that reference tenancy status.

2. Compliance Re-Evaluation

A tenancy.updated event is fired. This event is consumed by the compliance engine, which re-evaluates any associated complianceChecks. This ensures that post-tenancy compliance obligations (such as deposit return deadlines and final inspection requirements under the Renters' Rights Act) are surfaced promptly.

3. Check-Out Inspection Notification

An in-app notification is sent to all organisation admins linked to the tenancy. The notification prompts them to schedule a check-out inspection for the property. Admins will see this notification in their dashboard the morning after the sweep runs.

---

Schedule

Field	Value
Cron expression	0 1 * * *
Runs at	01:00 UTC, every day
Type	Nightly batch

---

Affected Entities

Entity	What changes
tenancies	status set to 'ended'
properties	Downstream property state updated to reflect active tenancy ending
notifications	In-app notification created per admin per transitioned tenancy
complianceChecks	Re-evaluation triggered by tenancy.updated event

---

What Triggers This Workflow

The workflow is scheduled only — it is not triggered by any user action or API call. It runs automatically each night. There is no manual trigger or on-demand API endpoint for this sweep.

---

What Is NOT Affected

• Tenancies with no endDate set are ignored entirely.
• Tenancies already in ended, disputed, or any non-active status are skipped.
• The sweep does not delete tenancy records — it only updates the status field.

---

Admin Experience

When one or more tenancies under your organisation are auto-ended by the sweep, you will see an in-app notification the following morning. The notification will:

• Identify the property and tenancy that ended
• Prompt you to schedule a check-out inspection
• Link directly to the tenancy record

Compliance checks will already be re-running in the background — you do not need to trigger them manually.

---

Developer Notes

• The workflow emits a standard tenancy.updated domain event. Any listeners subscribed to this event will be invoked as normal.
• If a tenancy transitions due to the sweep, the event payload will include the updated status: 'ended' field.
• Downstream systems (e.g. reporting, audit logs) that consume tenancy.updated will process these transitions on the same nightly cycle.