Monthly Analytics Snapshot Pre-computation

Available from: v0.1.336

Overview

The monthly analytics snapshot workflow automatically pre-computes portfolio-level performance metrics on the 1st of every month at 3:00 AM UTC. Snapshots are persisted to storage so that dashboards and reports can read pre-computed results rather than running expensive aggregations on demand.

Schedule

Cron: 0 3 1 * *

The workflow triggers automatically — no manual intervention is needed. Each run produces one snapshot record per portfolio, stamped with the reporting month.

Metrics Computed

Total Deposits Protected

The aggregate count and cumulative value of deposits currently under protection within the portfolio at the end of the preceding month.

Average Time-to-Release

The mean number of days elapsed between tenancy end date and the completion of the deposit release, calculated across all releases finalised in the preceding month.

Deduction Win/Loss Rates by Property Type

For each property type (e.g. flat, house, HMO), the proportion of deduction line items that were:

Accepted by the tenant (win)
Successfully disputed by the tenant (loss)
Partially settled

This surfaces which property segments generate the most contested deductions.

Compliance Score Trends

Month-over-month delta in aggregated compliance scores derived from complianceChecks. Highlights portfolios improving or declining in regulatory adherence over time.

Dispute Frequency

The number of disputes raised as a proportion of total deposit releases processed in the period. Tracked at portfolio level to identify systemic issues early.

Data Sources

The workflow reads from the following entities to compute each snapshot:

Entity	Metrics Informed
`tenancies`	Deposit totals, property type segmentation, time-to-release
`depositReleases`	Time-to-release, dispute frequency baseline
`depositReleaseDeductions`	Win/loss rate inputs
`disputeOutcomes`	Win/loss resolution, dispute frequency
`complianceChecks`	Compliance score trend inputs
`checkInReports`	Condition baseline for deduction context
`checkOutReports`	Condition comparison for deduction context

Storage

Computed snapshots are written to the analytics_snapshots table. Each record contains:

portfolio_id — the portfolio the snapshot belongs to
snapshot_month — ISO 8601 year-month identifier (e.g. 2025-06)
computed_at — UTC timestamp of when the snapshot was generated
metrics — JSON object containing all computed metric values

Alternatively, where analytics_snapshots is not present in the schema, metrics are serialised as JSON and stored within existing reporting structures.

Retention

Snapshots are cumulative — each monthly run appends a new record rather than overwriting previous ones. This enables historical trend queries without re-aggregating raw data.

Performance Impact

Because metrics are pre-computed during the early hours of the 1st, analytics views and reporting endpoints can read directly from snapshot records during business hours. This reduces query latency significantly for portfolios with large tenancy volumes.

First Run

The first snapshot is generated on the next 1st of the month following deployment of v0.1.336. Prior months will not be back-filled automatically.

Related Features

Compliance Score Monitoring
Deposit Release Workflow
Dispute Resolution Tracking