Module: Connect — Call Center (Phase 3)

The standout module — what no competitor ships. Call-center workforce orchestration: connect variants, shifts, benchmark-driven call packages, a live agent cockpit, KPIs, and per-agent commissions, wired to CloudTalk.

Responsibilities

• Let Supervisors define Connect variants (weekday / time windows the calling is allowed in) and build Shifts that must fall inside those windows.
• Release campaigns to Connect-Agents (each a real person with a commission rate); an agent sees only released campaigns.
• On shift activation, build benchmark-driven Packages: lock the top-N unworked targets by score into the shift's Packages (position = benchmark desc).
• Drive the live agent cockpit and capture Call records (via CloudTalk webhooks + cockpit dispositions), broadcast in real time.
• Derive KPIs and commissions from calls; feed Bandit outcomes.

Integration boundary

• DialerProvider interface — CloudTalk (client-chosen). Push call lists per shift; use the native power dialer so agents auto-advance; receive outcome, recording URL, and duration via webhook (or CloudTalk WebSocket where offered, webhook as fallback).
• Its own NestJS module behind the interface: mockable, retried, timed-out, cost-tracked.

Connect variants, shifts & packages

Supervisor defines ConnectVariant (weekday/time windows, connect steps/script)
  → Supervisor builds Shift(agent, campaign, starts_at, target_count) inside those windows
  → on activation: lock top-N unworked targets by benchmark into Packages (up to 4 per shift)
  → push call list to CloudTalk (DialerProvider)
  → Connect-Agent works the cockpit; power dialer auto-advances through the Package
  → each call: CloudTalk webhook + cockpit disposition → Call row → target pipeline transition

Realtime is delivered over Socket.IO (channels per-user, per-shift, per-campaign); a CloudTalk event reaches the cockpit UI in < 500ms.

Agent cockpit

A focused screen — the standout UI:

• Current target's full context: all enrichment + benchmark + breakdown + outreach history.
• The connect script attached to the Connect variant.
• A disposition form: gatekeeper reached (y/n), decision-maker reached (y/n), interest (none/low/high), appointment scheduled (y/n), notes.
• Next call — CloudTalk's power dialer auto-advances; the cockpit updates to the next target in the Package.

The 8-stage connect pipeline

Dispositions move the target through:

Targets
  → Not reached (follow-up)
  → Reached (gatekeeper blocked)
  → Reached (appointment interest)
  → Appointment scheduled
  → No interest (follow-up)
  → Finally rejected
  → Do not contact

• Bandit success = Appointment scheduled. Failure = not reached / no interest / finally rejected / do-not-contact. Intermediate states (gatekeeper blocked, appointment interest) fire no Bandit event.
• Reaching an appointment routes the target toward Closing (warm handoff).

KPIs (derived)

• Reach rate — connected / dialed.
• Gatekeeper quote — got past the gatekeeper to a decision-maker.
• Interest / trust rate — interested / reached.
• Appointment rate — appointments scheduled / reached.
• Per-agent commission — from outcomes × the Connect-Agent's commission rate.

Key services / jobs

• ScheduleShift, ActivateShift — locks the benchmark-driven Packages, pushes to CloudTalk.
• ProcessCallWebhook — verify signature, write the Call, transition the target, emit the Bandit outcome, broadcast over Socket.IO.
• RecordDisposition — cockpit form submit.
• CalculateAgentKpis / CalculateCommission.

Async: dialer sync runs on the connect-sync BullMQ queue; inbound events on webhooks. Business logic lives in NestJS services; input validated via DTOs (class-validator) / zod.

Acceptance

• A Supervisor defines a Connect variant and schedules a Shift inside its windows; activation locks the top-N targets by benchmark into Packages and pushes them to CloudTalk.
• A Connect-Agent works the cockpit in benchmark order (only for released campaigns); dispositions + CloudTalk webhooks produce Call records and pipeline transitions in real time.
• KPIs (reach, gatekeeper quote, interest, appointment) and commissions compute correctly; an Appointment scheduled records a Bandit success.
• Tests use a faked DialerProvider; webhook signature validation is covered; no real API calls in CI.

Screens (see 04-design-workflow)

• Agent Cockpit — the focused live call screen (prototype priority), built from shared React/shadcn components.
• Shift scheduling board (Supervisor) — part of the Dashboard / Campaigns area.