feat: auto enroll into org as student and oauth improvements

2026-05-20 08:32:56 +01:00
parent d21d89f250
commit 71fbb2101c
18 changed files with 482 additions and 21 deletions
@@ -0,0 +1,298 @@
+# Onboarding Platform Showcase PRD
+
+## Status
+- Draft
+
+## Date
+- May 20, 2026
+
+## Purpose
+Redesign the new-user onboarding flow so creators see (a) what their public-facing **org landing page** can look like and pick a theme, and (b) land in a workspace that is already pre-populated with **goal-relevant demo courses** instead of an empty `/courses` page. The goal is to move first impression from "blank slate" to "this platform is alive and ready for me."
+
+## Problem Statement
+Today's onboarding is a sterile 2-step form:
+
+1. Org name + slug + full name
+2. Goal + source + locale
+
+Then the user is dropped onto `/org/{slug}/courses?create=true` — a page with zero courses, zero branding decisions made, and no visible evidence that ClassroomIO is anything more than a CRUD form for a course list. Two problems compound:
+
+1. **The landing page feature is invisible.** We ship 8 production-quality landing page themes (`minimal`, `bold`, `classic`, `saas`, `tech`, `studio`, `corporate`, `terminal`) with full preview PNGs, but new users never see them — they have to discover Settings → Landing Page on their own.
+2. **The workspace looks empty.** New users have no reference for what a "real" ClassroomIO course looks like (sections, lessons, video embeds, certificates). They have to imagine the product from a blank canvas.
+
+Result: low activation, high time-to-first-meaningful-action, and the impression that the platform is thinner than it actually is.
+
+## ICP (Primary)
+1. SaaS founders launching a product academy.
+2. Independent course creators selling self-paced cohorts.
+3. Operations leaders running employee/compliance training.
+4. Customer-success teams running customer enablement.
+
+## Target Jobs-To-Be-Done
+1. Quickly evaluate whether ClassroomIO can produce a school site that looks like the creator's brand.
+2. See what a "good" course structure looks like on the platform without having to build one to find out.
+3. Get to a publishable-feeling state in a single session.
+
+## Confirmed Product Decisions
+1. **Theme picker** is a real step (not a passive preview gallery). The user's selection is persisted to `organization.landingPage.theme`.
+2. **Auto-seed goal-relevant demo courses** — no extra picker step. The existing `goal` answer in metadata drives which course set lands in the org.
+3. **Step order**: `org-setup → theme-picker (+ course preview) → user-metadata → seed-and-redirect`.
+4. **Course source**: a **new curated demo set** authored in code (not the existing `seedCourses()` templates in `packages/db/src/utils/seed/course.ts`, which were built for E2E/dev seeding).
+
+## Non-Goals (v1)
+- AI-generated courses from a URL — that is a separate initiative tracked in `prd/onboarding-ai-bootstrap/`.
+- Custom theme editing inside onboarding (colors, hero text, logo upload). The full landing-page editor stays in `/settings/landingpage`.
+- Letting the user pick *which* demo courses to seed. Goal-mapping is opinionated.
+- Multi-language demo course content. v1 demo courses ship in English only; the user's `locale` choice affects UI chrome but not seeded course text.
+- Surfacing demo courses on the **public** landing page automatically — they seed as unpublished/draft so the org owner reviews first.
+
+## Data Sources Checked
+- `apps/dashboard/src/routes/(auth)/onboarding/+page.svelte`
+- `apps/dashboard/src/lib/features/onboarding/api/onboarding.svelte.ts`
+- `apps/dashboard/src/lib/features/onboarding/utils/constants.ts`
+- `apps/dashboard/src/lib/features/onboarding/utils/types.ts`
+- `apps/dashboard/src/lib/features/onboarding/components/verify-email-modal.svelte`
+- `apps/dashboard/src/lib/features/onboarding/components/welcome-modal.svelte`
+- `apps/dashboard/src/lib/features/org/utils/landing-page.ts`
+- `apps/dashboard/src/lib/utils/types/org.ts`
+- `apps/dashboard/src/lib/features/settings/pages/landingpage.svelte`
+- `apps/dashboard/static/templates/*.png` (8 theme preview PNGs)
+- `packages/ui/src/custom/org-landing-page/` (theme component implementations)
+- `apps/api/src/routes/onboarding/onboarding.ts`
+- `apps/api/src/services/onboarding.ts`
+- `apps/api/src/services/course/course.ts` (createCourse pattern)
+- `apps/api/src/services/course-import/course-import.ts` (bulk lesson/section seed pattern)
+- `apps/api/src/routes/organization/course-import.ts`
+- `packages/db/src/schema.ts` (organization, course, courseSection, lesson, courseImportDraft)
+- `packages/db/src/utils/seed/course.ts` (existing dev seed, reference only)
+- `packages/utils/src/validation/onboarding/onboarding.ts`
+- `prd/onboarding-ai-bootstrap/README.md` (sibling initiative, must not conflict)
+- `prd/org-landing-page-theme-picker [DONE]/README.md` (foundation shipped Apr 2026)
+
+## Current Baseline (As-Is)
+1. `ONBOARDING_STEPS = { ORG_SETUP: 1, USER_METADATA: 2 }` — two steps.
+2. `createOrganizationWithOwner` creates the org with `landingPage = createDefaultLandingPageSettings()` (theme `'minimal'`, default hero copy from `defaultLandingPageHero` in `apps/dashboard/src/lib/features/org/utils/landing-page.ts:33`).
+3. `updateUserOnboarding` saves goal/source/fullname, updates user locale, and the API class redirects to `/org/{siteName}?welcomePopup=...`.
+4. No course creation happens during onboarding. The "create=true" query param on the courses page is unused.
+5. Theme picker exists *only* in `/settings/landingpage` — never surfaced to first-time users.
+6. The 8 theme preview PNGs at `apps/dashboard/static/templates/{theme}.png` are already shipped and used by the settings editor; we can reuse them as-is.
+
+---
+
+## Proposed Experience
+
+### Step 1: Account + Org Basics (unchanged)
+- `fullname`
+- `orgName`
+- `siteName`
+
+On submit: existing `createOrganizationWithOwner` runs and the org is created with the default `'minimal'` theme.
+
+### Step 2 (NEW): Theme Picker + Course Preview
+
+Single screen, two stacked sections inside the existing centered onboarding card.
+
+**Top section — "Pick a look for your school"**
+- Responsive 4-up grid (collapsing to 2-up on small screens) of 8 theme cards.
+- Each card: `/templates/{theme}.png` + theme display name + a subtle "Selected" ring when active.
+- Default selection: `minimal` (matches what was already saved at org-create time).
+- Clicking a card sets local `fields.theme`. No autosave — persistence happens on "Continue".
+
+**Bottom section — "Your workspace will come pre-loaded"**
+- 4 static course-tile mockups (using the same primitive `/courses` uses) showing variety: one `SELF_PACED`, one `LIVE_CLASS`, one `COMPLIANCE`, one with a certificate badge.
+- Subtext: "We'll add a few sample courses you can edit, publish, or delete."
+- These tiles are *previews only* — not the actual courses that will be seeded. They communicate "you're not landing in an empty room."
+
+**Continue**: calls a new `POST /onboarding/select-theme` with `{ theme }`, then advances to step 3.
+**Back**: returns to step 1 without losing org data (org is already persisted; back is just a step-state change).
+
+### Step 3: User Metadata (unchanged in shape, behavior change on submit)
+- `goal` (radio)
+- `source` (radio)
+- `locale` (select)
+
+On submit: existing `updateUserOnboarding` runs, **then** the route invokes `seedDemoCoursesForGoal(orgId, profileId, goal)` synchronously (with a short timeout — see FR-4) before returning. Response includes `seededCourseIds` so the frontend can surface them in the post-redirect view.
+
+### Post-Onboarding
+- Redirect to `/org/{siteName}/courses` (drop the `?create=true` marker — it was unused and the page is no longer empty).
+- The existing `welcomePopup` modal still fires and now references the seeded courses ("We added a few sample courses to get you started — feel free to edit or delete them.").
+
+---
+
+## Functional Requirements
+
+### FR-1 — Theme Persistence
+- `POST /onboarding/select-theme` accepts `{ theme: OrgLandingPageTheme }`, validates against `landingPageThemes` (8 values), and patches `organization.landingPage.theme` using a `jsonb_set` so other landing-page fields (hero, navItems, footer) remain untouched.
+- Endpoint requires `authMiddleware`. Caller must be the owner of the org tied to the current onboarding session.
+- Idempotent — re-submitting the same theme is a no-op success; re-submitting a different theme overwrites.
+
+### FR-2 — Curated Demo Course Set
+- Define `DEMO_COURSES_BY_GOAL: Record<OnboardingGoal, DemoCourseSpec[]>` in `packages/db/src/utils/demo-courses/index.ts`.
+- Each `DemoCourseSpec` includes: `title`, `description`, `overview` (markdown), `type` (`SELF_PACED` | `LIVE_CLASS` | `COMPLIANCE` | `PUBLIC`), `bannerImage` (URL to a static asset), optional `certificate` config, and a `sections: Array<{ title, lessons: Array<{ title, note, videos? }> }>` tree.
+- Lesson content: title + ~150-word markdown `note` + optional public YouTube embed reference. No file uploads required.
+- Target size: 2 courses per goal, 3 sections per course, 3 lessons per section — enough to look real, cheap to seed.
+- Mapping (initial):
+  - `sell-online` → "Launch Your First Paid Course" (`SELF_PACED`), "Marketing Funnels for Course Creators" (`SELF_PACED`)
+  - `teach-online` → "Designing Engaging Live Cohorts" (`LIVE_CLASS`), "Active Learning Toolkit" (`SELF_PACED`)
+  - `employees` → "Workplace Compliance 101" (`COMPLIANCE`, with certificate), "Manager Essentials" (`SELF_PACED`)
+  - `customers` → "Customer Onboarding Bootcamp" (`SELF_PACED`), "Product Mastery" (`PUBLIC`)
+  - `expanding-platform` → one of each `type` (broadest exposure)
+
+### FR-3 — Demo Course Seeding
+- New service `seedDemoCoursesForGoal(orgId, profileId, goal)` in `apps/api/src/services/onboarding/seed-demo-courses.ts`.
+- Internally calls a new query helper `createDemoCoursesForOrg(orgId, ownerProfileId, specs)` in `packages/db/src/queries/onboarding/demo-courses.ts` that runs **inside a single transaction**, mirroring the insert shape used by `createCourse` (`apps/api/src/services/course/course.ts:181`) — group + course + group-member + default section + welcome newsfeed — extended for the additional sections/lessons.
+- Seeded courses are created with `isPublished: false` and `isTemplate: false` so they appear as drafts the owner can edit/publish/delete.
+- **Idempotency**: before seeding, the service counts the org's non-template courses; if `>= 1`, it skips. This guards against double-submit of `/update-metadata`.
+
+### FR-4 — Seed Failure Doesn't Block Redirect
+- The `/update-metadata` handler awaits `seedDemoCoursesForGoal` with a 5-second timeout.
+- On timeout or thrown error: log structured warning (`onboarding.seed_demo_courses.failed` with `orgId`, `goal`, `error`), return `{ success: true, data: { ...metadata, seededCourseIds: [] } }` so the user is not stranded. A background retry is **not** in scope for v1.
+
+### FR-5 — Theme Picker UI
+- New `apps/dashboard/src/lib/features/onboarding/components/theme-picker.svelte`.
+- Renders the 8-theme grid + the 4-tile preview block.
+- Theme list is sourced from `landingPageThemes` in `apps/dashboard/src/lib/features/org/utils/landing-page.ts:22` (single source of truth).
+- Theme labels are translation keys: `onboarding.theme.{themeId}`.
+- Preview tiles reuse the existing course-card primitive (the one rendered at `/courses` — verify the component name during implementation; if multiple exist, pick the one used in the published course list).
+
+### FR-6 — Step Constants & Progress Bar
+- Update `ONBOARDING_STEPS` to `{ ORG_SETUP: 1, THEME_PICKER: 2, USER_METADATA: 3 }`.
+- The existing progress bar (`apps/dashboard/src/routes/(auth)/onboarding/+page.svelte:24`) uses `Object.keys(ONBOARDING_STEPS).length`, so it auto-scales.
+- Back button is enabled on steps 2 and 3 (currently only enabled when `step > ORG_SETUP`).
+
+### FR-7 — Validation
+- Add `ZOnboardingSelectTheme` in `packages/utils/src/validation/onboarding/`:
+  ```ts
+  export const ZOnboardingSelectTheme = z.object({
+    theme: z.enum(LANDING_PAGE_THEMES)
+  });
+  ```
+- `LANDING_PAGE_THEMES` must be a single shared literal exported once (either from `@cio/ui/custom/org-landing-page/types` or `@cio/utils`) and reused by both the validator and the frontend `landingPageThemes` array.
+
+### FR-8 — Frontend Type Hygiene
+- Per CLAUDE.md frontend conventions:
+  - All request/response types live in `apps/dashboard/src/lib/features/onboarding/utils/types.ts`, inferred from the API (`typeof classroomio.onboarding['select-theme'].$post`).
+  - **No** type definitions in `.svelte.ts` files.
+  - All copy lives in `apps/dashboard/src/lib/utils/translations/en.json` under `onboarding.theme.*`.
+
+### FR-9 — Observability
+- Emit funnel events (whatever analytics layer the dashboard currently uses — verify before instrumenting):
+  - `onboarding.theme_picker_viewed`
+  - `onboarding.theme_selected` (with `theme` property)
+  - `onboarding.demo_courses_seeded` (with `goal`, `count`, `latency_ms`)
+  - `onboarding.demo_courses_seed_failed` (with `goal`, `error`)
+- These are additive; do not remove existing onboarding analytics.
+
+### FR-10 — Self-Host Safety
+- The demo-course seed payload is a static constant in `@cio/db`. Self-hosted instances get the same behavior with no external dependencies (no LLM calls, no image hosting beyond static assets bundled with the dashboard).
+- Default theme `'minimal'` continues to be applied at org-create time, so users who skip step 2 (e.g. close the tab) still end up with a working landing page.
+
+---
+
+## Proposed API + Service Design
+
+### Validation — `packages/utils/src/validation/onboarding/`
+- `ZOnboardingSelectTheme` — see FR-7.
+- `ZOnboardingUpdateMetadata` — **no shape change**; behavior change is server-side only.
+
+### Routes — `apps/api/src/routes/onboarding/onboarding.ts`
+- `POST /onboarding/select-theme` *(new)* — auth + zValidator(ZOnboardingSelectTheme); delegates to `selectOnboardingTheme(profileId, orgId, theme)`.
+- `POST /onboarding/update-metadata` *(extended)* — after `updateUserOnboarding`, awaits `seedDemoCoursesForGoal(orgId, profileId, goal)` with timeout/log-on-fail behavior in FR-4. Returns `{ success: true, data: { ...existing, seededCourseIds } }`.
+
+### Services — `apps/api/src/services/onboarding/`
+- `select-theme.ts` — `selectOnboardingTheme(profileId, orgId, theme)`. Authorizes profile is owner; calls query helper.
+- `seed-demo-courses.ts` — `seedDemoCoursesForGoal(orgId, profileId, goal)`. Idempotency check + delegate to query helper.
+
+### Queries — `packages/db/src/queries/`
+- `organization/landing-page.ts` — `updateOrgLandingPageTheme(orgId, theme)` using `jsonb_set`.
+- `onboarding/demo-courses.ts` — `createDemoCoursesForOrg(orgId, profileId, specs)` running in a single transaction.
+
+### Data — `packages/db/src/utils/demo-courses/index.ts`
+- Static export `DEMO_COURSES_BY_GOAL` + types. Lives in `@cio/db` so both API services and (future) self-host migration tools can import it.
+
+### Dashboard — `apps/dashboard/src/lib/features/onboarding/`
+- `utils/constants.ts` — add `THEME_PICKER` step.
+- `utils/types.ts` — extend `OnboardingField` with `theme?: OrgLandingPageTheme`; add request type for the new endpoint.
+- `api/onboarding.svelte.ts` — add `submitTheme(theme)` method; update step dispatcher; advance to `USER_METADATA` on success.
+- `components/theme-picker.svelte` *(new)* — the new step UI.
+- `routes/(auth)/onboarding/+page.svelte` — extend the if/else block to a 3-way switch; wire back-button to step down through all 3 states.
+
+---
+
+## Data Model Changes
+**None at schema level.** Both new behaviors reuse existing tables:
+- Theme selection writes to the existing `organization.landingPage` jsonb column.
+- Demo courses use the existing `course`, `courseSection`, `lesson` tables (no new columns).
+
+No migration is required. (Aligns with the user's standing rule: schema edits stop at a passing `@cio/db` build; migrations are handled outside this workflow.)
+
+---
+
+## Translation Keys (new)
+Under `onboarding.theme.*` in `apps/dashboard/src/lib/utils/translations/en.json`:
+- `heading` — "Pick a look for your school"
+- `subheading` — "You can change this anytime in settings."
+- `demo_heading` — "Your workspace will come pre-loaded"
+- `demo_subheading` — "We'll add a few sample courses you can edit, publish, or delete."
+- `minimal`, `bold`, `classic`, `saas`, `tech`, `studio`, `corporate`, `terminal` — display labels.
+
+---
+
+## UX Quality Bar
+Per the user's standing UI rules:
+- Use `@cio/ui/base/card` for theme tiles, with `ui:ring-primary` for selected state (color tokens prefixed `ui:` for theme resolution).
+- Use the same course-card primitive `/courses` uses for the preview tiles — do not invent a new card. If a suitable component does not exist, extract one rather than copy-pasting markup.
+- No hardcoded user-facing strings.
+- No native `<input>` / `<label>` in this UI; use `@cio/ui/custom/*-field` wrappers if any inputs are needed (none required for v1, but applies if scope grows).
+
+---
+
+## Rollout Plan
+1. **Phase 1 — internal alpha (week 1)**: ship behind a soft "feature flag" by gating step 2 on an env var (`PUBLIC_ONBOARDING_SHOWCASE_ENABLED`) so we can test in staging without exposing to prod signups.
+2. **Phase 2 — 25% cloud rollout (week 2)**: bucket by user ID hash.
+3. **Phase 3 — 100% cloud (week 3, assuming no regression)**: remove the env gate; legacy 2-step flow code is deleted.
+4. **Phase 4 — self-host**: ships with the next normal release; no toggle needed (no external dependencies).
+
+---
+
+## Success Metrics
+1. **+15% relative lift in onboarding completion** (step-3 submit / step-1 view).
+2. **+30% relative lift in "user views the public landing page in their first session"** — proxy for "did the theme picker land?"
+3. **+50% relative lift in "user edits at least one course in their first session"** — proxy for the seeded courses being a real lure into the editor.
+4. **Median onboarding time stays under 4 minutes** — adding a step must not bloat the flow.
+5. **<2% seed-failure rate** measured by `onboarding.demo_courses_seed_failed` over `onboarding.theme_selected`.
+
+---
+
+## Risks and Mitigations
+1. **Risk**: Seeded demo courses confuse users who think they're real templates they have to keep. **Mitigation**: courses ship as `isPublished: false` drafts; welcome popup copy explicitly says "feel free to edit or delete"; a small "Sample" badge on the course card is a v1.1 candidate.
+2. **Risk**: Demo course content drifts and looks dated. **Mitigation**: content is in code (`DEMO_COURSES_BY_GOAL`) and reviewed every release; quarterly content refresh is owned by the content team.
+3. **Risk**: Seed transaction is slow on large goal sets (5+ courses × 9 lessons each = lots of inserts). **Mitigation**: bulk insert with a single transaction; cap demo set at 2 courses × 3 sections × 3 lessons; FR-4 timeout protects the user-facing path.
+4. **Risk**: Goal value drift (someone adds a 6th goal to `GOALS`) breaks the `DEMO_COURSES_BY_GOAL` lookup. **Mitigation**: TypeScript `Record<OnboardingGoal, ...>` makes this a compile-time error; CI catches it.
+5. **Risk**: Conflict with the parallel `onboarding-ai-bootstrap` PRD. **Mitigation**: that PRD adds a *website URL* step and AI-generated courses; this PRD's theme step and curated demo set are orthogonal and can stack later (AI courses replace demo courses when AI flow runs; theme picker is shared). Document in `prd/onboarding-ai-bootstrap/README.md` once both are merged.
+6. **Risk**: Theme choice in onboarding gets overwritten by the default-applied theme on org create. **Mitigation**: org create still applies `'minimal'` default; the new `/select-theme` endpoint runs after and uses `jsonb_set` to patch only the theme field — confirmed by manual E2E in the verification plan.
+
+---
+
+## Open Questions
+1. Should the preview tiles in step 2 be **personalized** with the org's just-entered name (e.g. "Welcome to {orgName}") to feel less canned? Adds complexity for marginal trust gain.
+2. Should the welcome popup link directly to one of the seeded courses to encourage immediate editing, vs. dropping the user on the courses list?
+3. Should `locale != 'en'` users see a banner saying "Sample courses are in English — translate or replace as you like" instead of getting English-language content silently?
+4. Do we want to display a "Sample" pill on the seeded courses in the course list so the owner remembers what's editable demo content? (Recommendation: yes, but ship in v1.1.)
+5. Should the theme picker also let the user upload a logo? (Recommendation: no — keep scope tight; logo upload lives in settings.)
+
+---
+
+## Verification Plan
+1. **Build**: `pnpm --filter @cio/db build && pnpm --filter @cio/api build && pnpm --filter @cio/dashboard check`
+2. **Manual E2E**, fresh user per run:
+   - Sign up → confirm step 1 looks unchanged.
+   - Step 2: 8 themes render with correct preview PNGs; selection ring follows clicks; "Continue" persists theme.
+   - Step 3: submit metadata → confirm redirect to `/org/{slug}/courses` populated with 2 demo courses matching the chosen goal.
+   - Public landing page `/{slug}` renders the picked theme (not `minimal`).
+   - Settings → Landing Page reflects the picked theme.
+   - Open a seeded course → confirm sections, lessons, and lesson notes render.
+3. **Goal coverage**: run the E2E once per `goal` value (5 runs) — confirm correct course set per goal.
+4. **Idempotency**: replay `POST /onboarding/update-metadata` via dev tools — confirm no duplicate courses created.
+5. **Seed failure path**: temporarily throw inside `createDemoCoursesForOrg` — confirm user still completes onboarding and lands on `/courses` (empty but functional), and that `onboarding.demo_courses_seed_failed` log line emits.
+6. **Theme override**: change theme via back button in step 2 multiple times — last selection wins.