PSA/ee/docs/plans/2025-11-17-onboarding-dashboard-checklist-plan.md

MSP Dashboard Onboarding Checklist Plan (2025-11-17)

Goal

Implement a persistent onboarding checklist within the MSP dashboard that reflects real-time completion for critical setup areas (identity/SSO, client portal domain, data import, calendar sync, managed email) and nudges admins to finish configuration.

Scope

• Dashboard UI additions (cards, drawer, quick-start replacements).
• Shared onboarding progress data hook/services.
• Lightweight analytics wiring for interactions.
• No new backend features beyond surfacing existing state via actions/services.

Out of Scope

• New onboarding steps beyond the five defined areas.
• Automated testing, QA, or production rollout tasks.
• Client portal visualization; MSP dashboard only.

---

Phase 1 – Progress Data Layer

1. Inventory signals: Document which existing actions/services expose status for each area and whether additional metadata is needed (e.g., portalDomainActions, importActions, calendarActions, managedDomainActions, SSO connection state from oauthAccountLinks).
2. Create shared hook: Add server/src/components/dashboard/hooks/useOnboardingProgress.ts exporting a hook that aggregates useSWR (or existing React Query) calls to the relevant endpoints and normalizes into OnboardingStep objects { id, title, status, lastUpdated, ctaHref, blocker }.
3. Add lightweight API if needed: If any status requires combining multiple action responses, expose a server action (e.g., server/src/lib/actions/onboarding-progress.ts) that fetches state server-side to reduce client round-trips.
4. Emit analytics state: Within the hook, when statuses transition to complete, dispatch posthog.capture('onboarding_step_completed', { step_id }) to preserve historical completion timing.

Phase 2 – Checklist Drawer Component

1. Component scaffold: Create server/src/components/dashboard/OnboardingChecklist.tsx rendering a sticky/right-rail drawer. Accept hook data as props to keep it presentational.
2. Step rendering: For each OnboardingStep, show title, description, progress indicator (icon or progress bar for multi-subtask steps like data import). Include CTA buttons linking to the corresponding settings path (provided in step metadata).
3. Blocker messaging: If step.blocker exists, show inline alert so admins understand prerequisites (e.g., “Add an MSP admin user before enabling SSO”).
4. Completion affordance: When all steps complete, show celebratory state plus a button to “Invite clients” (deep-link to /msp/clients?create=true).

Phase 3 – Dashboard Integration

1. Integrate hook: Import useOnboardingProgress in server/src/components/dashboard/Dashboard.tsx, call it once, and pass data into both existing quick-start cards and the new checklist component.
2. Quick Start refresh: Replace static QuickStartCard list with onboarding-aware cards that show status (e.g., badge for Complete, progress spinner otherwise) and disable navigation when prerequisites unmet.
3. Layout adjustments: Update the grid to accommodate the checklist drawer on desktop while keeping a collapsible drawer trigger on mobile (use CSS utility classes that already exist in the project’s design system).
4. Event wiring: Ensure clicks on CTA buttons fire posthog events with { step_id, action: 'cta_click' } for future funnel insights.

Phase 4 – Visual Refinement & Content

1. Iconography + copy: Select consistent icons for each step using lucide-react imports already used in the dashboard. Update copy to explicitly mention in-app features (e.g., “Verify client portal domain via DNS challenge”).
2. Status badges: Introduce a small badge component (reuse existing Badge or StatusPill) to show Blocked, In Progress, Complete states.
3. Empty states: Define design for when data is loading or when no steps remain. Use existing skeleton loaders to maintain visual consistency.
4. Documentation stub: Add a short README snippet (e.g., docs/configuration_guide.md appendix) describing how the checklist derives its state so future contributors can extend it.

---

Implementation Notes

• Stick to existing action patterns; don’t introduce new database tables.
• All new UI components should live under server/src/components/dashboard to keep dashboard concerns localized.
• Use centralized route constants if available; otherwise, define CTA hrefs near the hook to avoid hard-coded strings scattered across components.