Purpose / UX

Show top-level tenant KPIs as tiles at the top of the dashboard. Tiles: Total Devices, Devices with Alerts (30d), Active Certifications, Total Facilities, Total Assets, Active Subscriptions.

Data Fields & Source

• totalDevices — source: devices table/API. COUNT where tenant_id.
• devicesWithAlerts30d — source: alerts store. COUNT(DISTINCT device_id) WHERE created_at >= now() - 30d.
• activeCertifications — source: monthly_rollup or denorm facility.currentCertLevel (count facilities classified as Active).
• totalFacilities — source: facilities table.
• totalAssets — source: facility hierarchy (assets/locations/spaces). Sum by tenant.
• activeSubscriptions — source: subscriptions table (facility subscription statuses).

Backend logic

• Use cached counts where heavy (summary endpoint caches for 30s–1m).
• For certifications, read denorm facility.currentCertLevel if available; otherwise compute from latest monthly_rollup month.

API Stub

GET /v1/dashboard/summary?tenantId=TEN_1
Response:
{
  "totalDevices":124,
  "devicesWithAlerts30d":12,
  "activeCertifications":5,
  "totalFacilities":12,
  "totalAssets":34,
  "activeSubscriptions":5
}

Acceptance Criteria

Values reflect tenant data at request time. Tiles link to devices list, alerts view, certifications list, facilities list, subscriptions list.

Edge Cases

Tenant with zero facilities: show zeros & CTA to onboard facility.

Purpose / UX

Bar chart + sparkline: totalDevices vs devicesWithAlerts (30d) with a 30‑day alerts timeseries sparkline. Clicks filter device table to devices with alerts.

Data Fields & Source

• devices: devices table (device.id, device.name, device.status, device.lastReading).
• alertsTimeseries: alerts table (created_at, severity, device_id).

Backend logic

• totalDevices = COUNT(devices)
• devicesWithAlerts = COUNT(DISTINCT device_id WHERE created_at >= now()-30d)
• Timeseries by grouping alerts by DATE(created_at)

API Stub

GET /v1/dashboard/devices-overview?tenantId=TEN_1&days=30
Response:
{
  "totalDevices":124,
  "devicesWithAlerts":12,
  "alertsTimeseries":[{"date":"2025-07-25","count":3}, ...]
}

Acceptance Criteria

Clicking devicesWithAlerts opens a devices table filtered to those that had alerts; include lastReading.

Edge Cases

Toggle to count unique device-days vs raw alerts.

Filters

• Facility (all / specific)
• Severity (info / warn / critical)
• Parameter (CO2, Temp, Humidity, etc.)
• Date range (default 30 days)

Purpose / UX

Show counts by certification state and a small expiring list with CTA to renew.

Data Fields & Source

facility.currentCertLevel (preferred cached field) OR compute from monthly_rollup for latest month. Fields: facilityId, name, certLevel, certExpiryDate, certStartDate, subscriptionStatus.

Backend logic

If facility.currentCertLevel exists, use it; otherwise derive from latest monthly_rollup per facility using certification gates. Count by state.

API Stub

GET /v1/dashboard/certifications?tenantId=TEN_1
Response:
{
  "totals": { "platinum":2, "gold":5, "silver":3, "pending":2, "grace":1, "suspended":0 },
  "expiring": [{"facilityId":"F3","name":"Shop C","daysRemaining":25}, ...]
}

Acceptance Criteria

Counts reflect latest computed levels. Expiring list ordered by daysRemaining ascending.

Filters

Level (platinum/gold/silver) • Expiring (≤90/≤30/≤7 days)

Purpose / UX

Show month-by-month counts per certification level for N months (default 12). Toggle to show/hide levels.

Why use MonthlyRollup

Historical trends MUST use monthly_rollup as Device×Bucket is ephemeral.

Data & Backend

For each month M in window: for each facility fetch monthly_rollup for M, aggregate within_pct across required parameter families, apply gates to classify level, tally counts per level.

API Stub

GET /v1/dashboard/cert-trend?tenantId=TEN_1&months=12
Response:
{
  "months": ["2025-08","2025-07", ...],
  "series": {
    "platinum": [2,3,2,...],
    "gold": [5,4,5,...],
    "silver": [10,9,11,...],
    "paused": [1,1,0,...]
  }
}

Acceptance Criteria

For each month, classification equals facility-level gate application from monthly_rollup.

Filters

Months window (3/6/12/24) • Facility type (Retail/Office/School)

Purpose / UX

Table listing worst-performing 5 facilities (lowest within_pct or worst primary failing parameter) for current month.

Data Fields & Source

monthly_rollup (scope='facility', month=currentMonth): param, within_pct, expected, actual, flags.

Backend logic

Compute failureScore (configurable), sort ascending, return top 5. Include primaryFailParam = param with lowest within_pct.

API Stub

GET /v1/dashboard/top-failures?tenantId=TEN_1&limit=5
Response:
[
  { "facilityId":"F1","name":"Shop A","primaryFailParam":"CO2","withinPct":58.4,"expected":720,"actual":432 },
  ...
]

Acceptance Criteria

Top 5 reflect current month monthly_rollup. Missing monthly_rollup → mark as insufficient data.

Filters

Facility type • Parameter family • Only expected ≥ X

Purpose / UX

Compact card grid showing N primary devices. Each tile: Device name, primary param & value, timestamp (facility local TZ), online/offline badge.

Data Fields & Source

device.lastReading on devices: { param, value, timestamp } and device.lastSeen / device.status.

API Stub

GET /v1/dashboard/device-mini-grid?tenantId=TEN_1&limit=12
Response:
{ "items": [ { "deviceId":"D1","name":"CO2 Sensor 1","param":"CO2","value":412,"timestamp":"2025-08-22T10:00:00Z","status":"online","assetId":"A1" }, ... ] }

Acceptance Criteria

Tile displays lastReading.value and timestamp in facility timezone.

Filters

Facility • Parameter • Status (online/offline)

Purpose / UX

Map with facility pins. Color indicates certification status. Hover: facility name, cert level, days remaining, link to facility page.

Data Fields & Source

facilities: facilityId, name, lat, lon, timezone, facility.currentCertLevel (preferred), certExpiryDate, subscriptionStatus. Fallback: compute from latest monthly_rollup.

Backend logic

Return geo points with certLevel and daysRemaining. Pin color rules applied in UI.

API Stub

GET /v1/dashboard/facility-map?tenantId=TEN_1
Response:
[ {"facilityId":"F1","name":"Shop A","lat":25.123,"lon":55.321,"certLevel":"Gold","expiry":"2026-06-01","daysRemaining":285}, ... ]

Filters

Level (All / Platinum / Gold / Silver / Payment Due / Suspended) • Expiring (≤90/30/7 days) • Facility type

Edge Cases

Missing lat/lon → facility appears in side list with CTA to add coordinates.

Purpose / UX

Rolling feed of recent alerts for tenant with severity badges and quick links.

Data Fields & Source

alerts: alert_id, created_at, device_id, facility_id, param, value, severity, message.

API Stub

GET /v1/facilities/{id}/alerts?tenantId&since=2025-07-01
Response: [ { alert objects... } ]

Filters

Severity • Parameter • Facility • Date range