Technical Feature Overview

Welcome Calls & Restricted Coach Role — Technical Scope

Engineering scoping doc · Last updated June 3, 2026

Goal

Introduce a restricted “contractor coach” role and wire up the welcome-call flow: shared-pool booking → Zoom call → contractor-scoped dashboard → automated post-call survey → per-contractor performance tracking.

This doc maps what already exists, the real gaps, the two architectural decisions, and an effort breakdown. It is written to be reviewed with the tech lead before any implementation.

Systems involved

Repo	Role
`enrich-cms`	Strapi 4.14.6 backend — content types, policies, email, cron
`coaching-platform`	React 18 monorepo (coach/admin portal) — where contractors will log in
`enrich-student-portal`	Student-facing portal — booking entry point

What already exists

Meetings + Calendly + Zoom — largely wired.

meeting content type (enrich-cms/src/api/meeting/content-types/meeting/schema.json): meetingTime, calendlyUri, calendlyCancelUri, joinUrl, meetingReason, relation to contact (student), relation to event.
Calendly webhook controller (enrich-cms/src/api/meeting/controllers/meeting.js) handles invitee.created / invitee.canceled / invitee_no_show.created, creating/deleting meetings and logging event rows.
The Zoom link is already captured from Calendly’s scheduled_event.location.join_url (meeting.js:88). If Calendly is connected to a Zoom account, no direct Zoom API integration is required.
Existing TODO at meeting.js:92 (set student to welcomeMeetingComplete if event is welcome call) confirms the welcome-call flow was anticipated.

Coach assignment infra.

coach type (enrich-cms/src/api/coach/content-types/coach/schema.json): contacts (assigned students, oneToMany), studentDistributionWeight (round-robin weighting), per-coach calendlyLink + quickMeetingCalendlyLink, user relation to users-permissions.user, eventNotificationSettings (json).

Email + scheduling infra.

SendGrid via strapi.plugins['email'].services.email.send(...); custom-email plugin with templated coach notifications (enrich-cms/src/plugins/custom-email/server/services/coach-feedback.js).
Klaviyo plugin for marketing/reminder flows.
Cron framework (enrich-cms/config/cron-tasks.js), America/New_York tz, established “scheduled job” pattern.
BullMQ/Redis available for deferred/background work.

The gaps

1. The role model is a monotonic hierarchy — this is the crux

enrich-cms/src/policies/roles.js defines authorization as a numeric ladder:

admin: 5, coach: 4, taskmaster: 3, resume reviewer: 2, company/school admin: 1, authenticated: 1
checkRole(role, least) => roles[role] >= least

So is-coach (src/policies/is-coach.js) passes for anyone weight ≥ 4 (coach and admin). A contractor is not a lower rung on this ladder — they need a narrow orthogonal slice: only their own welcome-call students and their own meetings, with none of the general coach powers. The “>= weight” model can’t express that cleanly.

Frontend gates independently by Strapi role.id:

coaching-platform/apps/coaching-platform/src/App.js:76 — isCoach = user?.role?.id === 3; nav driven by NAV_LINKS.coach / NAV_LINKS.admin.
Login (packages/shared-lib/src/auth/authentication/Login.js) stores jwt, userId, coachId, etc. in localStorage.

Work required:

New Strapi role (e.g. welcome-call-coach) + users-permissions permissions.
New entry in roles.js and new scoping policies that filter to own records (e.g. is-welcome-call-coach, plus row-level “owns this meeting/contact” checks) — not just a weight threshold.
Frontend: new role.id branch, a dedicated NAV_LINKS set, route guards hiding all admin/coach pages.
An invite flow for contractors. Current InviteAdmin.js only supports ['company admin', 'school admin'] via /api/users/invite-admin — needs extending or a parallel invite-coach path.

2. `meeting` has no `coach` relation

Meetings link to the student but not the coach who runs the call. Without it, a contractor cannot query “my calls.” Work: add coach relation to the meeting schema; populate it at booking time (from the round-robin assignment / Calendly host email).

3. Shared-pool booking does not exist

Today each coach has an individual calendlyLink. “Student picks from one shared calendar across all contractors, auto-assigned” is new. Two options — see Decision 1.

4. No post-call survey / feedback mechanism

No survey or feedback content type, no post-meeting trigger. Work: a delayed/scheduled job (cron sweep over past meetingTime, or a BullMQ delayed job scheduled at booking) that sends the student a survey email; a new welcome-call-feedback content type to store responses; aggregation for per-contractor performance. Hook point already flagged at meeting.js:92.

The two decisions that drive cost

Decision 1 — Booking approach

(A) Calendly round-robin / collective event type pointed at a Zoom-connected pool. Reuses the existing webhook path almost as-is; assignment comes from Calendly. Low effort, recommended for v1.
(B) Custom in-portal availability + scheduler. Full control, but a large build (availability modeling, slot generation, timezone handling, conflict resolution, Zoom meeting creation via API). ~5x the effort of (A).

Decision 2 — Role-scoping convention

Confirm with tech lead: net-new restricted role + per-row “own data” policies (recommended), vs. any existing limited-user convention to follow. Defines the policy surface area for everything else.

Effort estimate (engineering-days, fast path = Decision 1A)

Phase	Scope	Estimate
0	Decisions + Calendly event-type config	0.5–1 d
1	Restricted role: Strapi role, `roles.js`, scoping policies, FE guards/nav, contractor invite flow	4–7 d
2	`coach` relation on `meeting`; populate on booking; round-robin assignment via `studentDistributionWeight`	3–5 d
3	Contractor dashboard: scoped “my upcoming/past calls” endpoint + view	2–4 d
4	Post-call survey: delayed job, survey email, `welcome-call-feedback` type, per-contractor rollup	4–6 d
—	Testing (TDD per repo conventions), QA, staging verification	folded into each phase

Total (Path A): ~2–4 weeks. Path B (custom booking) adds roughly +1.5–3 weeks to Phase 2 alone.

Risks / unknowns

Calendly plan limits — round-robin/collective event types and the Zoom connection may require a specific Calendly tier; confirm account capability.
Role-id coupling — FE uses hardcoded role.id integers; new role id must be consistent across environments (staging/prod Strapi role ids can differ).
Webhook trust — Calendly webhook endpoint should verify signatures before creating meetings (worth confirming current state).
No-show / cancellation handling for the survey job (don’t survey a no-show); existing no-show event handling can drive this.

Out of scope (v1)

Contractor payouts/payment automation (track call counts only).
Custom analytics dashboards beyond basic per-contractor performance.
Custom booking calendar (only if Decision 1B is chosen).