docs(phase5b): self-paced enrollment documentation + website integration contract

- PHASE5B_SELF_PACED_ENROLLMENT.md: the full design doc.
- RUNBOOK_SELF_PACED_ENROLLMENT.md: operational runbook for /admin -> Programs.
- WEBSITE_ENROLLMENT_INTEGRATION.md: the complete contract for the separate website team —
  endpoint, auth, request/response schema, idempotency/retry rules, student matching, minor/
  no-email behavior, error responses, what not to send, local testing, production-secret
  handling. Written to be usable without reading the Platform API source.
- REMOTE_AND_SELF_PACED_ARCHITECTURE.md: closes the self-registration/curriculum-assignment/
  delivery-mode/enrollment-model gaps this doc previously flagged as Phase 5+ scope.
- ENGINEERING_SOP.md: new §15. LAB_ARCHITECTURE.md, PRODUCTION_VALIDATION_CHECKLIST.md,
  README.md, platform/README.md: cross-references and a Phase 5B production-validation section.
This commit is contained in:
2026-08-25 12:10:13 -05:00
parent 23f881884d
commit 1c08a30c7f
9 changed files with 558 additions and 28 deletions
+28 -21
View File
@@ -45,11 +45,12 @@ this flow specifically — see the Phase 4.1 report for the full run results.
## What's genuinely missing for a real self-paced product (Phase 5, not built here)
1. **No self-registration / public enrollment.** A student row is created only by an instructor
(`POST /api/admin/students`, admin/owner RBAC-gated). There is no public "sign up" surface.
This is almost certainly the right call to leave alone for now — it's explicitly a Phase 5+
product/business decision (course commerce, is it free, who's allowed to enroll), not an
infrastructure gap.
1. **No self-registration / public enrollment surface.** Still true, still deliberate — Phase 5B
built the boundary a *separate* public website will call
(`POST /api/integrations/enrollments`, see `docs/PHASE5B_SELF_PACED_ENROLLMENT.md` §11 and
`docs/WEBSITE_ENROLLMENT_INTEGRATION.md`) rather than a public sign-up form here. A student
row can now be created automatically by a trusted server-to-server enrollment event, but there
is still no browser-facing "sign up" page anywhere in this codebase — that's the website's job.
2. ~~**No real student authentication.**~~ **Closed in Phase 5A.** Students now have real
credentials (email+password or login-identifier+password, `password_hash`/`scrypt` reusing
@@ -59,25 +60,31 @@ this flow specifically — see the Phase 4.1 report for the full run results.
/api/login` still works for not-yet-converted pilot rows only; it's rejected (409) the moment
an account has real credentials or a pending activation token.
3. **`curriculum_assignments.student_id` is schema-ready but unwired.** The table has supported
a direct per-student curriculum assignment (independent of any cohort) since Phase 2B
(`CONSTRAINT curriculum_assignment_target CHECK (cohort_id IS NOT NULL OR student_id IS NOT
NULL)`) — but nothing in the application ever reads or writes that column today; there's only
one curriculum path, so nothing has needed to differentiate yet. Not a gap that blocks
self-paced delivery now (every student already sees the one path with no gate), but the
moment a second curriculum path exists, this is where per-individual assignment lands — the
schema was designed for exactly this and doesn't need a migration to support it.
3. ~~**`curriculum_assignments.student_id` is schema-ready but unwired.**~~ **Addressed
differently in Phase 5B.** `curriculum_assignments` itself remains unwired, unchanged — but
the real problem it was meant to eventually solve (which curriculum a given student sees) is
now solved at the enrollment layer instead: `enrollments.curriculum_path` snapshots
`programs.curriculum_path` per enrollment. `curriculum_assignments` is still available for a
future direct per-student assignment need outside the program/enrollment model — it wasn't
removed, just not the mechanism Phase 5B ended up using. See
`docs/PHASE5B_SELF_PACED_ENROLLMENT.md` §4.
4. **No delivery-mode concept anywhere.** In-person, remote, and self-paced sessions aren't
distinguished in any data model today, and nothing currently needs them to be — capacity
planning, the reaper, and academic records all behave identically regardless of how a student
is attending. Worth being aware this is unmodeled, not worth building a taxonomy for before a
real product reason exists (YAGNI).
4. ~~**No delivery-mode concept anywhere.**~~ **Closed in Phase 5B.**
`programs.delivery_mode`/`enrollments.delivery_mode` (`self_paced`/`cohort`/`hybrid`) is now
a real, snapshotted field. Capacity planning, the reaper, and Lab lifecycle mechanics still
behave identically regardless of delivery mode — this only affects how enrollment/entitlement
is modeled, not infrastructure.
5. **No self-paced enrollment/entitlement model.** ~~Closed in Phase 5B~~ — see
`docs/PHASE5B_SELF_PACED_ENROLLMENT.md` for `programs`/`enrollments`, server-enforced
entitlement (pending/future/expired/cancelled), server-derived completion, and the resulting
self-paced student dashboard.
## What Phase 4.1 deliberately did NOT do here
No signup flow, no student password/email auth implementation, no per-student curriculum
assignment route, no payments, no public course catalog, no held/premium scenario content. All
explicit non-goals per this phase's authorization. Student authentication (item 2, above) was
closed in Phase 5A; the rest remain open, unmodeled by design (YAGNI) until a real product
reason exists.
explicit non-goals per this phase's authorization. Student authentication (Phase 5A) and the
self-paced enrollment/entitlement model (Phase 5B) have both since been built; a public
self-registration *page*, real payment processing, and a Parent/Guardian portal remain
deliberately out of scope — see `docs/PHASE5B_SELF_PACED_ENROLLMENT.md` §12.