cohort-enrollment — Implementation Plan

cohort-enrollment — Implementation Plan

Alias: ce — invoke as /pipeline ce <section> or /discovery ce <section>. Section IDs in YAML + commits still use the canonical slug cohort-enrollment.

Context

cohort-enrollment is job #7 in docs/future-jobs.md and maps to the single "Cohort enrollment integration" bullet in Phase 3 of docs/fabled10x-website-implementation-plan.md (line 209). It delivers the full applicant funnel for a paid cohort: a public catalog of upcoming cohorts, a waitlist form for pre-announce interest capture, an authenticated application form, an editorial review dashboard, acceptance emails with single-use payment links, Stripe-backed enrollment, and an enrolled-student view inside the existing /products/account.

This job explicitly does not build the cohort delivery platform itself — no lessons, no video player, no Zoom integration, no chat, no automated application scoring, no calendar integration. Those are out of scope per docs/future-jobs.md §7. This job's job is "the site-side half of running a cohort": surface it, capture interest, take applications, decide who's in, take payment, and show a student their enrollment. Everything after payment is handled out-of-band by the operator emailing logistics manually — a future cohort-delivery job adds the rest.

The job depends entirely on two prior jobs having shipped through the full TDD pipeline:

• website-foundation (alias wf) — site shell, design tokens, MDX pipeline, content loader core, Zod validators, email capture pattern, dynamic sitemap/robots.
• storefront-auth (alias sa) — Postgres + Drizzle stack, Auth.js v5 magic-link, users/sessions/purchases tables, middleware.ts route protection, Stripe client singleton, Stripe webhook route, /products/account overview page.

Neither job has shipped yet (pipeline/active/session.yaml shows zero completed sections as of 2026-04-11) — every contract in this plan is drawn from currentwork/{website-foundation,storefront-auth}/phase-*.md, not from live code. email-funnel is a peer of this job (job #4 in future-jobs.md) and ships src/db/migrations/0001_email_funnel.sql; this job's migration is 0002_cohort_enrollment.sql. If the two ship in reverse order, drizzle-kit generate advances the numbers automatically and the tables don't conflict.

Four strategic decisions resolved with the user at jobbuild time:

1. Payment mechanism — Pre-provisioned Stripe Price IDs per cohort. Each Cohort MDX carries a stripePriceId field; operator creates the Stripe Price in the dashboard and pastes the price_xxx ID. Acceptance emails carry a signed one-time token that redirects to a Checkout Session against that price. Mirrors sa's Product.stripePriceId pattern exactly.
2. Application auth — Magic-link sign-in required on /cohorts/[slug]/apply. sa's Auth.js v5 middleware matcher is extended to cover the route. cohort_applications.userId is a non-nullable fk to users.id.
3. Review UI — Gated admin dashboard at /admin/cohorts/applications. An ADMIN_EMAILS env allowlist is enforced by a new shared src/app/admin/layout.tsx. Mirrors the /admin/email-funnel pattern planned in currentwork/email-funnel/README.md; the same env var is shared across both jobs.
4. Enrollee view — Extend sa's /products/account with a Cohorts section. Adds a new /products/account/cohorts subroute plus a "My cohorts" card on the existing overview. No parallel /cohorts/account tree — reuses sa's layout, sign-out button, and auth gate.

Out of scope (explicit non-goals): cohort delivery platform, automated application scoring, calendar integration, recurring/subscription billing for cohorts, payment plans, partial refunds, waitlist auto-promotion when a seat opens up, A/B-tested acceptance email copy, public application-status pages, and SMS notifications. Decline and waitlist-decision emails ship with generic fixed copy; per-cohort template variants are a future job.

What Already Exists

Already in the repo today (2026-04-11)

• Next.js 16.2.3 App Router scaffold — React 19.2.4, Tailwind 4, strict TS, @/ → src/. (package.json, tsconfig.json, next.config.ts)
• Content schemas — src/content/schemas/{content-tier,content-pillar,episode,source-material,index.ts}
• Test infra — Vitest 2.1.8 + jsdom, @testing-library/jest-dom/vitest via src/__tests__/setup.ts, MSW 2.7 installed, coverage thresholds 70/80/80/80 (vitest.config.ts)
• Source docs — docs/fabled10x-website-implementation-plan.md, docs/future-jobs.md, docs/fabled10x-brand-identity.md, docs/fabled10x-launch-strategy.md, docs/fabled10x-revenue-projections.md

Delivered by website-foundation (prereq — NOT YET SHIPPED when this plan is written)

This job reuses these wf outputs and cannot start until they exist.

• Brand design tokens (src/app/globals.css from wf 1.3) — --color-{ink,parchment,ember,steel,mist,signal} + semantic aliases --color-{background,foreground,muted,accent,link}. Tailwind surface: bg-accent, text-muted, border-mist, text-link, bg-parchment, font-display.
• <Container> layout primitive (src/components/site/Container.tsx from wf 1.4) — mx-auto w-full max-w-5xl px-6 md:px-10, as prop (div/section/main/article).
• <Header> + NAV_ITEMS (src/components/site/Header.tsx from wf 1.4) — this job MODIFIES NAV_ITEMS to insert /cohorts between /cases and /products.
• <Footer> (src/components/site/Footer.tsx from wf 1.4) — reused unchanged.
• <EmailCapture> + captureEmail server action (src/components/capture/* from wf 4.1) — shape reference for <WaitlistForm>. Not reused directly because the waitlist writes to a dedicated Resend audience (RESEND_COHORT_WAITLIST_AUDIENCE_ID) + a cohort_waitlist DB row, not the main newsletter audience.
• Content loader core (src/lib/content/loader.ts from wf 2.2) — loadContent<T>({directory, schema}) helper. src/lib/content/cohorts.ts is a thin wrapper.
• MDX pipeline (next.config.ts wrapped with createMDX(), mdx-components.tsx at project root, wf 2.1) — reused unchanged; cohort MDX files slot in at src/content/cohorts/*.mdx.
• Zod validators (src/content/schemas/validators.ts from wf 1.2) — MODIFY to append CohortSchema + CohortApplicationInputSchema.
• Episode / Case schema shape (src/content/schemas/{episode,case}.ts from wf) — reference for the Cohort interface shape + as const tuple + z.enum(TUPLE) pattern.
• generateStaticParams + dynamicParams = false (wf 3.3/3.5) — same pattern for /cohorts/[slug] and /cohorts/[slug]/apply.
• JSON-LD via dangerouslySetInnerHTML (wf 4.3) — same pattern for Course + Offer structured data on cohort detail pages.
• Dynamic sitemap (src/app/sitemap.ts from wf 4.4) — MODIFY to append public cohort URLs. Gated routes (/cohorts/*/apply, /cohorts/*/checkout, /admin/*, /products/account/cohorts) NEVER appear in the sitemap.
• robots.ts (src/app/robots.ts from wf 4.4) — MODIFY to disallow /admin/* + cohort gated subroutes.
• resend dependency (installed by wf 4.1) — reused for waitlist + applicant + decision emails.
• zod dependency (installed by wf 1.2) — reused throughout.

Delivered by storefront-auth (prereq — NOT YET SHIPPED when this plan is written)

This job also depends on sa having shipped.

• Postgres + Drizzle stack (sa 2.1) — src/db/schema.ts, src/db/client.ts, drizzle.config.ts, docker-compose.yml, migrations under src/db/migrations/. This job adds 0002_cohort_enrollment.sql alongside sa's 0000_init.sql.
• users table (sa 2.1) — id (uuid pk), email (text unique), createdAt, lastSignInAt. The fk target for cohort_applications.userId, cohort_admissions.userId, cohort_enrollments.userId.
• purchases table (sa 2.1) — REFERENCE. The cohort Stripe flow intentionally does NOT insert into purchases — a cohort seat lives in its own cohort_enrollments row so the /products/account purchases list and the cohorts list are independent queries. The webhook branch distinguishes them by metadata.kind: 'cohort' | 'product'.
• Auth.js v5 config (sa 2.2, src/auth.ts) — auth() server helper + signIn + signOut actions. Reused verbatim.
• Middleware (middleware.ts from sa 2.3) — MODIFY. Extend the matcher to include /cohorts/:slug/apply, /cohorts/:slug/checkout, /admin/:path*, /products/account/cohorts.
• <SignInForm> + /login + /login/verify (sa 2.4) — reused unchanged as the redirect target for gated cohort routes.
• Stripe client singleton (src/lib/stripe/client.ts from sa 3.1) — reused by src/lib/cohorts/checkout.ts.
• resolveStripePriceId() (src/lib/stripe/price-map.ts from sa 3.1) — REFERENCE only. The cohort checkout resolver lives at src/lib/cohorts/checkout.ts and reads stripePriceId from the Cohort record directly; it does NOT reuse resolveStripePriceId because that helper is product-specific.
• Stripe webhook route (src/app/api/stripe/webhook/route.ts from sa 3.3) — MODIFY. The handler already verifies signatures and parses checkout.session.completed events; this job adds a branch that inspects metadata.kind and routes cohort events to a new handleCohortCheckout() helper instead of the existing product-purchase insert.
• runtime = 'nodejs' on the webhook route — reused.
• /products/account/page.tsx (sa 4.1) — MODIFY. Append a "My cohorts" card above the existing purchases list.
• <SignOutButton> (sa 4.3) — reused unchanged in /products/account/cohorts.
• Email helper pattern (src/lib/email/purchase-confirmation.ts from sa 3.5) — shape reference for every email this job ships. Direct new Resend(...) per helper, inline HTML string template, AUTH_RESEND_FROM for transactional, separate RESEND_FROM_COHORTS for this job's marketing-adjacent sends.

Gaps (must build fresh — wf/sa provide zero coverage)

• Cohort content schema + loader + catalog routes
• Cohort-specific DB tables (waitlist, applications, admissions, enrollments)
• Waitlist form + dedicated Resend audience wiring
• Application form + multi-step validation
• Admin allowlist gate + cohort review dashboard
• HMAC-signed one-time checkout token utility
• Cohort-branch webhook handler
• /products/account/cohorts extension

Feature Overview (10 Features, 4 Phases — condensed from 18)

Condensed 2026-04-12 via /condense ce — 8 pipeline runs saved. Each merged feature ships as one TDD pipeline section; sub-parts are documented inline in the phase files under #### ... headings.

Size guide: S = few hours, single file. M = half day, 2–3 files. L = full day, 4+ files. XL = multi-day, new content type + DB + UI + external integration.

Total rough job size: L — matches docs/future-jobs.md §7 sizing. Smaller than storefront-auth (XL) because every payments + auth primitive already exists and this job only extends them. Larger than testimonials-results (M) because it introduces persistence, an admin UI, an HMAC-signed token flow, and a Stripe webhook branch.

Dependency Graph (condensed)

Phase 1: Catalog (public)
│
│   1.1 → 1.2 → 1.3               ← sequential, shared loader
│
v
Phase 2: Waitlist + Persistence
│
│   2.1 → 2.2                     ← sequential (form+action+email merged)
│
v
Phase 3: Application Flow
│
│   3.1 → 3.2                     ← sequential (page+form+action+email merged)
│
v
Phase 4: Review + Payment + Account
│
    4.1 → 4.2 → 4.3               ← sequential (list+detail merged, Stripe half merged, account+SEO merged)

Hard dependencies (post-condense):

• new 1.1 → new 1.2 — loader validates loaded MDX entries against CohortSchema (merged from old 1.1+1.2).
• new 1.2 → new 1.3 — both index and detail pages call getAllCohorts() / getCohortBySlug() / getCohortBuckets().
• Phase 1 → Phase 2 — <WaitlistForm> is rendered inside /cohorts/[slug] from new 1.3.
• new 2.1 → new 2.2 — server action inserts into cohort_waitlist (table from new 2.1); submit action calls the confirmation email helper (merged from old 2.2+2.3).
• Phase 2 → Phase 3 — application submit writes to cohort_applications and checks cohort_waitlist for upgrades.
• new 3.1 → new 3.2 — server action validates FormData against CohortApplicationInputSchema; page renders form; action calls applicant email (merged from old 3.2+3.3+3.4).
• Phase 3 → Phase 4 — admin dashboard queries cohort_applications rows.
• new 4.1 → new 4.2 — decide action triggers decision email, which carries the signed checkout token; webhook branch reads metadata.applicationId + metadata.cohortSlug set by the checkout redirect handler (merged from old 4.1+4.2 and 4.3+4.4).
• new 4.2 → new 4.3 — the account cohorts list queries cohort_enrollments rows; SEO polish adds nav + sitemap + JSON-LD (merged from old 4.5+4.6).

New Content Types Required

Cohort lives at src/content/schemas/cohort.ts and is re-exported from src/content/schemas/index.ts alongside Episode, Case, Product, SourceMaterial. Content files at src/content/cohorts/*.mdx follow the same export const meta = {...} + MDX body convention from wf/sa.

CohortApplicationInput lives at src/content/schemas/cohort-application.ts. It is NOT a content type that ships MDX files — it's the server-side input type consumed by the submit action. Same file houses the APPLICATION_COMMITMENT_LEVELS tuple used by the form's select.

New DB Tables (Drizzle schemas, Postgres dialect)

Indexes:

• cohort_waitlist(cohort_slug) — waitlist admin filter + upgrade-lookup on application submit
• cohort_applications(cohort_slug, decision) — admin dashboard filter
• cohort_applications(user_id) — /products/account/cohorts list query
• cohort_admissions(application_id) — UNIQUE (implicit index)
• cohort_enrollments(user_id) — /products/account/cohorts list query
• cohort_enrollments(stripe_session_id) — UNIQUE, webhook idempotency

No changes to sa's existing users / sessions / verificationTokens / purchases tables.

Critical Files Reference

New files

Content schema + catalog (Phase 1)

Public catalog routes (Phase 1)

Persistence + waitlist (Phase 2)

Application flow (Phase 3)

Review + payment + account (Phase 4)

Modified files

Reference-only files (read, don't modify)

• src/content/schemas/{episode,case,product}.ts — shape to mirror for Cohort
• src/content/schemas/validators.ts — CaseSchema / ProductSchema are the templates for CohortSchema
• src/lib/content/loader.ts — core loadContent<T>() helper called by the cohort loader
• src/lib/content/{episodes,cases,products}.ts — loader API to mirror
• src/app/products/[slug]/page.tsx — detail page pattern (async, params: Promise<{slug: string}>, generateStaticParams, dynamicParams = false, JSON-LD inline)
• src/components/capture/EmailCapture.tsx — useActionState + server action shape for <WaitlistForm> + <ApplicationForm>
• src/lib/stripe/client.ts — Stripe SDK singleton
• src/lib/stripe/checkout.ts — createCheckoutSession pattern for createCohortCheckoutSession
• src/app/api/stripe/webhook/route.ts — webhook signature verification + idempotent insert pattern
• src/lib/email/purchase-confirmation.ts — inline HTML string email helper pattern
• src/auth.ts — auth() server helper
• middleware.ts — existing matcher (before modification)
• node_modules/next/dist/docs/01-app/02-guides/authentication.md — Next.js 16 auth guidance
• node_modules/next/dist/docs/01-app/03-api-reference/03-file-conventions/route.md — Route Handler signatures
• node_modules/next/dist/docs/01-app/02-guides/upgrading/version-16.md — params: Promise<...> breaking change

Verification Plan

Phase Documentation

• Phase 1: Catalog — Cohort schema, validator, loader, /cohorts index, /cohorts/[slug] detail
• Phase 2: Waitlist + Persistence — Drizzle migration, <WaitlistForm>, waitlist confirmation email
• Phase 3: Application Flow — application input schema, auth-gated apply page, <ApplicationForm>, applicant confirmation email
• Phase 4: Review + Payment + Account — admin dashboard, decision actions, HMAC checkout token, Stripe webhook branch, account cohorts view, SEO polish

Dependencies to Add

None. Every dependency this job uses is already installed by prior jobs:

• zod, resend — from wf 1.2 / wf 4.1
• postgres, drizzle-orm, drizzle-kit — from sa 2.1
• next-auth@5, @auth/drizzle-adapter — from sa 2.2
• stripe — from sa 3.1
• vitest, @testing-library/* — from the Next.js scaffold

If email-funnel ships first and introduces react-email + @react-email/components, the decision email in Phase 4.3 MAY migrate to React Email as a follow-up polish. This is NOT a blocking dependency — the phase file ships inline HTML strings and flags the possible upgrade in its Open Items.

Environment Variables

Required before the matching phase can be verified end-to-end. All are server-only (no NEXT_PUBLIC_ prefix).

All new variables are added to a new root .env.example if one doesn't exist yet, or appended to the existing one from wf/sa. The Phase-2 / Phase-4 red tests fail loudly if any required variable is missing.

Open Items (Resolve During Implementation)

• Cohort capacity enforcement — Cohort.capacity is a frontmatter field and /cohorts/[slug] derives isFull = enrolledCount >= capacity at render time. If a cohort sells out between acceptance and payment, the checkout route still lets the accepted applicant pay (since they were promised a seat). Enforcing "reject if oversold" would require a DB-level check in handleCohortCheckout() — noted as a follow-up, NOT part of v1.
• Decision email format — phase 4.3 ships inline HTML strings (matches sa 3.5's purchase-confirmation pattern). If email-funnel 2.1 has shipped src/lib/email/funnel/render.tsx first, the phase file flags "migrate to React Email in a follow-up" but does NOT block on it.
• Acceptance window length — ACCEPTANCE_WINDOW_DAYS = 14 in src/lib/cohorts/constants.ts. Not an env var — changing it requires a redeploy, which is the right friction level for a policy knob.
• Waitlist-to-application upgrade — the application submit action queries cohort_waitlist for a row matching (email, cohortSlug) and, if present, sets cohort_applications.waitlistId. This is the only relationship between the two tables; no automatic waitlist-to-application promotion happens.
• Admin allowlist source — phase 4.1 reads ADMIN_EMAILS as a comma-separated env var. A DB-backed admins table is deferred; email-funnel plans the same choice, so both jobs share the env var. If either job later adds a DB-backed admin model, both jobs migrate together.
• Cohort seed copy — 1.3 ships two stub MDX files with placeholder title / summary / dates / price / stripePriceId: 'price_REPLACE_ME_…'. Real cohort content + real Stripe Price IDs are a separate concern and not part of this job.
• full status — listed in docs/future-jobs.md §7 but collapsed into the combination of manual enrolled status flag + the derived isFull check. The operator flips to enrolled once applications close so the index page filters correctly.
• Refund handling — refunds are manual (operator issues refund in Stripe dashboard, manually deletes the cohort_enrollments row). Automated refund webhook handling is a future job.
• Cohort delivery handoff — after enrollment, logistics (Zoom links, Slack invites, calendar invites) are sent manually by the operator. A future cohort-delivery job adds automation.

Section IDs for TDD Workflow (condensed)

Each feature maps to one section ID used by /discovery, /red, /green, /refactor. Section IDs use the canonical slug cohort-enrollment, not the alias ce. Condensed 2026-04-12 from 18 sections to 10 — see the Feature Overview table for which old IDs each new ID merges.

These IDs are consumed by pipeline/active/session.yaml and used as directory names under pipeline/active/.