Pulse — Build Plan

1. Vision & Goals

Pulse gives General Managers and Head Housekeepers a single, glanceable screen to monitor the live state of housekeeping operations — room cleaning progress, team productivity, learning engagement and guest-satisfaction scores.

  • Real-time, not batched — a 30s auto-refresh keeps the snapshot current.
  • Multi-property — admins see all companies at once; a GM sees only their own property.
  • Dark "stock-exchange" aesthetic — near-black canvas, luminous cyan accents, tabular figures.
  • Mobile-first — GMs check it from their phone, no laptop required.
  • Locked to a single view — invited GMs reach Pulse and Pulse only.

2. Architecture & Data Flow

Pulse never reads raw records on the client. All aggregation happens server-side in the getPulseData backend function, which returns a single summary object scoped to the caller.

  • Auth & scoping — getPulseData authenticates the caller and resolves their authorised company. Admins may select any company (or "all"); a PulseViewer is restricted to their invited company.
  • Aggregation — the pulseAggregates shared module reads active WaveSessions, WaveRooms, WaveRoomStages and CompanyEmployees, then computes snapshot, allocations, productivity and learning summaries for the selected period.
  • Response — a single JSON payload returns companies, isAdmin, companyName, snapshot, allocations, productivity, learning. RPS fields are placeholders until Part 2.
  • Client render — the /Pulse page calls getPulseData via React Query (30s refetchInterval) and hands the result to presentational sub-components.

3. Access Model & GM Invites

A PulseViewer entity records each invited GM. The employer invites them from the Pulse Access panel; a custom email (sendInviteEmail, mode "pulse_viewer") links straight to /Pulse — not the academy sign-up.

  • PulseViewer RLS — a viewer reads/updates only their own record; the inviting employer and admins manage it.
  • usePulseViewer hook — resolves viewer status and pins it to sessionStorage so the lock does not blink during refetches.
  • AppLayout lock — a pure Pulse viewer is redirected to /Pulse on any other route; an admin can escape via a sessionStorage bypass.
  • Auth gate — Pulse sends unauthenticated visitors to login, then lands them on Pulse.

4. Dashboard Components

Each panel is a focused, self-contained component under src/components/pulse/.

  • PulseHeader — sticky bar with live Brisbane clock, period toggle (Today/Week/Month/Year), property selector (admin) and refresh.
  • SnapshotCards — pending / in-progress / complete room counts plus total daily allocations.
  • AllocationsPanel — donut chart of service types (arrival / non-arrival / mid-service) with loyalty-tier breakdown.
  • MemberProductivityTable — per-member completions, actual vs target minutes, colour-coded variance.
  • LearningStats — total modules completed, active learners, per-member progress.
  • RpsPanel — live MTD/YTD Cleanliness and Guest-Satisfaction RPS versus the property KPI.

5. Mobile & Navigation

  • Standalone route at /Pulse — renders outside AppLayout so GMs never see the academy chrome.
  • Admins get a "Pulse" bottom-tab on mobile, between Q&A and Wave Access, with a cyan accent.
  • Pure Pulse viewers get a single "Pulse" tab; nothing else is reachable.
  • Desktop admins reach Pulse from the Admin dropdown under "Executive".

6. RPS Scoring — Manual Entry

Employers manually enter Cleanliness and Guest-Satisfaction RPS scores from the Wave admin. Each score is stored per company and rolls up into Month-to-Date and Year-to-Date averages measured against the property KPI, then surfaces live in Pulse.

  • Cleanliness RPS tab — KPI target 87 points. Guest Satisfaction RPS tab — KPI target 78.24 points, shown next to each tab.
  • Each entry stores the score, its date, the metric and the recording employer; MTD and YTD averages are computed automatically.
  • Pulse replaces the old placeholder tiles with live MTD/YTD values, the KPI, and a variance indicator (on track / below).
  • Part 2 remains: an automated TrustYou feed to populate these scores without manual entry.

7. Scalability & Future

  • Server-side aggregation keeps the client light — the model scales to many properties without shipping raw records.
  • One-tap mobile PDF report export is the next planned addition (mirrors the EmployerGuide jsPDF pattern).
  • Live-updating in-progress / completed counters and an arrivals-vs-departures gauge are slated once TrustYou data lands.
Pulse · Housekeeping Academy · Build Plan