LMS policies
LMS policies & decisions
Section titled “LMS policies & decisions”Audience: product, domain, backend, ux
Status: specced
Owns: product
Depends on: Lifecycle, Personas, System architecture
Document decisions here before encoding them in LMS app code.
Accepted (v1 — 2026-08)
Section titled “Accepted (v1 — 2026-08)”| ID | Topic | Decision |
|---|---|---|
| LMS-01 | Multi-role | One OL account may be learner + instructor + staff. CAP allows candidate + centre staff on the same OL account (not arbitrary persona stacking: assessor/AB mixes stay 409). |
| LMS-02 | Onboarding gate | Per-persona draft → submit. Learner: names, gender, country/state/LGA (OL Address) + schemaVersion. Instructor/staff onboard after invite. |
| LMS-03 | Content runtimes | Native authoring + SCORM 1.2 import. LMS owns module/item order (not SCORM 2004 sequencing). cmi5/xAPI later. |
| LMS-04 | Publish | Course owner and platform staff may publish / unpublish / delete. Co-instructors edit only. DELETE /authoring/courses/{id} hard-deletes when unused; otherwise archives (archived, catalogue-hidden). |
| LMS-05 | Co-instructors | course_instructors: owner | co_instructor. Owner manages assignments. |
| LMS-06 | Catalogue | Public browse of published courses and level offerings (GET /courses*, GET /level-offerings*; optional Bearer). Item bodies / player / assessments / enroll / checkout require authentication and active entitlement. Course thumbnails resolve as public Orchestrator assets (purpose containing thumbnail). |
| LMS-07 | Entitlements | self_pay, admin_grant, cap_recommendation, sponsor, level_offering, organization_seat. Orchestrator owns Organization; LMS stores organizationId + seat allocations. sponsor stays “someone paid.” |
| LMS-08 | Payment | LMS prices self-pay; client POST /enrollments/{id}/checkout; OL InitiatePayment (referenceType: lms_enrollment). Org-sponsored checkout returns settlement: organization_cohort and does not call Paystack — Organization. List price lives on Course.priceMinorUnits + CoursePriceRevision. The amount the learner paid is snapshotted on Entitlement and is not rewritten when catalogue price changes. In-flight unpaid checkout keeps the issued amount; retry after fail uses the current list price. |
| LMS-09 | CAP linkage | Optional sectorId, tradeId, qualificationLevelId, unitId on course (one LMS course per CAP unit). gRPC RecommendCourses still returns unit_ids as a 0-or-1 array. |
| LMS-10 | Certificates | LMS certificate is independent of CAP. Completion also emits lms.course.completed. |
| LMS-11 | Storage | LMS never uses Cloudinary SDK. Zip + media via OL assetId. SCORM zips use OL purpose=scorm_package (local package adapter; Cloudinary raw max is too small). Course thumbnails use a purpose containing thumbnail so signed upload-url stores them PUBLIC. LMS extracts/serves SCORM player. Later: S3/R2. |
| LMS-12 | Staff roles | admin, content_manager, support. Staff capabilities ⊇ instructor, broader scope. |
| LMS-13 | Instructors | Invited strictly by the platform. |
| LMS-14 | Level SKU | LevelOffering is the sellable snapshot of a CAP QualificationLevel. One published offering per level. Publish requires every member course PUBLISHED with a unitId. Enroll fans out child course entitlements; overlap charges remaining members only (sum of remaining item snapshots, or override minus owned snapshots). POST /level-enrollments/{id}/checkout uses referenceType: lms_level_enrollment. Child lms.enrollment.activated still fires. |
| LMS-15 | Staff person display | GET /staff always returns displayName, email, photoAssetId, and resolved photo (CAP person pattern). Name: onboarding first+last → LmsUser.displayName → email local-part. Photo is person-level on LmsUser (GET/PATCH /me/profile). |
| LMS-16 | Platform settings | Singleton LmsPlatformSettings for the admin Settings screen: contact email/phone plus terms, privacy, and refund. Each legal section is typed text or a PDF uploaded to OL storage (documentAssetId). settings.read / settings.write are staff admin only. |
| LMS-18 | Org bulk enrol | Per SKU JSON or CSV; consume OL cohort seats; refuse open self-pay for the same offering; learner cannot unenroll sponsored rows; org release until offering completed. |
Open (not v1 blockers)
Section titled “Open (not v1 blockers)”| ID | Topic | Notes |
|---|---|---|
| LMS-O1 | Certificate PDF template | System-generated vs uploaded template |
| LMS-O2 | Max quiz attempts defaults | Per-item override exists; platform default TBD |
| LMS-O3 | Sponsor Paystack path | v1 grant may record paymentId optionally; dedicated sponsor checkout later |
| LMS-O4 | OL organizations | Shipped directory. Paying tenants, staff, cohorts: Organization + ORG-* checklist. LMS admin learners + seat allocations grant organization_seat without rewriting the player. |
Architecture notes
Section titled “Architecture notes”lms_users.userIdunique → OLusers.id; all LMS FKs point atlms_users.id.- Two-layer authz: capability gate +
assertScope— RBAC. - SCORM playback is LMS-owned, not
res.cloudinary.com. IframeplayerUrl(…/player/scorm/{sessionId}/player?ct=).launchUrlis session JSON. Package files are…/content/{path}underSCORM_EXTRACT_DIR.ctis learner-bound; nested files accept query, cookie (HTTPSSameSite=None; Partitioned), header, or Referer. - Full topology: System architecture.