helix-engage/docs/superpowers/specs/2026-03-24-supervisor-module.md

Supervisor Module — Team Performance, Live Call Monitor, Master Data

Date: 2026-03-24 Jira: PP-5 (Team Performance), PP-6 (Live Call Monitor) Status: Approved design

---

Principle

No hardcoded/mock data. All data from Ozonetel APIs or platform GraphQL queries.

---

1. Admin Sidebar Nav Restructure

SUPERVISOR
  Dashboard             → /                  (existing team-dashboard.tsx — summary)
  Team Performance      → /team-performance  (new — full PP-5)
  Live Call Monitor     → /live-monitor      (new — PP-6)

DATA & REPORTS
  Lead Master           → /leads            (existing all-leads.tsx)
  Patient Master        → /patients         (existing patients.tsx)
  Appointment Master    → /appointments     (existing appointments.tsx)
  Call Log Master       → /call-history     (existing call-history.tsx)
  Call Recordings       → /call-recordings  (new — filtered calls with recordings)
  Missed Calls          → /missed-calls     (new — standalone missed call table)

Files: sidebar.tsx (admin nav config), main.tsx (routes)

---

2. Team Performance Dashboard (PP-5)

Route: /team-performance Page: src/pages/team-performance.tsx

Section 1: Key Metrics Bar

• Active Agents / On Call Now → sidecar (from active calls tracking)
• Total Calls → platform calls count by date range
• Appointments → platform appointments count
• Missed Calls → platform calls where callStatus: MISSED
• Conversion Rate → appointments / total calls
• Time filter: Today | Week | Month | Year | Custom

Section 2: Call Breakdown Trends

• Left: Inbound vs Outbound line chart (ECharts) by day
• Right: Leads vs Missed vs Follow-ups by day
• Data: platform calls grouped by date + direction

Section 3: Agent Performance Table

Column	Source
Agent	Agent entity name
Calls	Platform calls filtered by agentName
Inbound	Platform calls where direction: INBOUND
Missed	Platform calls where callStatus: MISSED
Follow-ups	Platform followUps filtered by assignedAgent
Leads	Platform leads filtered by assignedAgent
Conv%	Derived: appointments / calls
NPS	Agent entity npsscore
Idle	Ozonetel getAgentSummary API

Sortable columns. Own time filter (Today/Week/Month/Year/Custom).

Section 4: Time Breakdown

• Team average: Active / Wrap / Idle / Break totals
• Per-agent horizontal stacked bars
• Data: Ozonetel getAgentSummary per agent
• Agents with idle > maxidleminutes threshold highlighted red

Section 5: NPS + Conversion Metrics

• NPS donut chart (average of all agents' npsscore)
• Per-agent NPS horizontal bars
• Call→Appointment % card (big number)
• Lead→Contact % card (big number)
• Per-agent conversion breakdown below cards

Section 6: Performance Alerts

• Compare actual metrics vs Agent entity thresholds:
  • maxidleminutes → "Excessive Idle Time"
  • minnpsthreshold → "Low NPS"
  • minconversionpercent → "Low Lead-to-Contact"
• Red-highlighted alert cards with agent name, alert type, value

Sidecar Endpoint

GET /api/supervisor/team-performance?date=YYYY-MM-DD

• Aggregates Ozonetel getAgentSummary across all agents
• Returns per-agent time breakdown (active/wrap/idle/break in minutes)
• Uses Agent entity to get list of all agent IDs

---

3. Live Call Monitor (PP-6)

Route: /live-monitor Page: src/pages/live-monitor.tsx

KPI Cards

• Active Calls count
• On Hold count
• Avg Duration

Active Calls Table

Column	Source
Agent	Ozonetel event agent_id → mapped to Agent entity name
Caller	Event caller_id → matched against platform leads/patients
Type	Event call_type (InBound/Manual)
Department	From matched lead's interestedService or "—"
Duration	Live counter from event_time
Status	active / on-hold
Actions	Listen / Whisper / Barge buttons (disabled until API confirmed)

Data Flow

1. Sidecar subscribes to Ozonetel real-time events on startup
   • POST https://subscription.ozonetel.com/events/subscribe
   • Body: { callEventsURL: "<sidecar-webhook-url>", agentEventsURL: "<sidecar-webhook-url>" }
2. Sidecar receives events at POST /webhooks/ozonetel/call-event
3. In-memory map: ucid → { agentId, callerNumber, callType, startTime, status }
   • Calling / Answered → add/update entry
   • Disconnect → remove entry
4. GET /api/supervisor/active-calls → returns current map
5. Frontend polls every 5 seconds

Sidecar Changes

• New module: src/supervisor/
  • supervisor.controller.ts — team-performance + active-calls endpoints
  • supervisor.service.ts — Ozonetel event subscription, active call tracking
  • supervisor.module.ts
• New webhook: POST /webhooks/ozonetel/call-event
• Ozonetel event subscription on onModuleInit

---

4. Master Data Pages

Call Recordings (/call-recordings)

Page: src/pages/call-recordings.tsx

• Query: platform calls where recording is not null
• Table: Agent, Caller, Type, Date, Duration, Recording Player
• Search by agent/phone + date filter

Missed Calls (/missed-calls)

Page: src/pages/missed-calls.tsx

• Query: platform calls where callStatus: MISSED
• Table: Caller, Date/Time, Branch (callsourcenumber), Agent, Callback Status, SLA
• Tabs: All | Pending | Attempted | Completed (filter by callbackstatus)
• Not filtered by agent — supervisor sees all

---

5. Agent Entity Fields (Already Configured)

GraphQL Field	Type	Purpose
ozonetelagentid	Text	Ozonetel agent ID
sipextension	Text	SIP extension
sippassword	Text	SIP password
campaignname	Text	Ozonetel campaign
npsscore	Number	Agent NPS score
maxidleminutes	Number	Idle time alert threshold
minnpsthreshold	Number	NPS alert threshold
minconversionpercent	Number	Conversion alert threshold

All custom fields use all-lowercase GraphQL names.

---

6. File Map

New Files

File	Purpose
helix-engage/src/pages/team-performance.tsx	PP-5 dashboard
helix-engage/src/pages/live-monitor.tsx	PP-6 active call monitor
helix-engage/src/pages/call-recordings.tsx	Call recordings master
helix-engage/src/pages/missed-calls.tsx	Missed calls master
helix-engage-server/src/supervisor/supervisor.controller.ts	Supervisor endpoints
helix-engage-server/src/supervisor/supervisor.service.ts	Event subscription + active calls
helix-engage-server/src/supervisor/supervisor.module.ts	Module registration

Modified Files

File	Change
helix-engage/src/components/layout/sidebar.tsx	Admin nav restructure
helix-engage/src/main.tsx	New routes
helix-engage-server/src/app.module.ts	Import SupervisorModule