LMS integration v1

# LMS integration v1

Integrate Yawp with school learning-management and student-information systems so assignments, rosters, launches, and grades can move between Yawp and systems schools already use.

## Source

Granola meeting: `3fbd5f2d-e409-42bd-b585-fed305edd5cd`, **Summer priorities — assignment types, LMS integration, and reporter**, 2026-05-26 1:31 PM CDT.

The call named Canvas, Blackboard, PowerSchool, Google Classroom, and Blackbaud. LMS integration was treated as a major sales/adoption unlock, especially for college use.

## Recommendation

Build the integration layer around standards first:

- **LTI 1.3 / LTI Advantage first.** This gives LMS launch, user/course context, Deep Linking, Names and Roles, and Assignment and Grade Services.
- **OneRoster second.** This gives a shared model for roster and gradebook exchange across K-12/SIS integrations.
- **Native APIs only where needed.** Canvas, Blackboard, Google Classroom, PowerSchool, and Blackbaud all have platform-specific surfaces, but using those first would fragment the architecture.

Official-source research:

- 1EdTech says OneRoster 1.2 supports rostering and gradebook services across REST and CSV, including users, classes, enrollments, line items, results, categories, and score scales. Source: https://www.1edtech.org/standards/oneroster
- Canvas exposes REST resources for assignments, enrollments, submissions, LTI registrations, names/roles, line items, scores, and related LMS resources. Source: https://canvas.instructure.com/doc/api/
- Canvas Deep Linking can create assignment/module items and pass grading information such as `lineItem.scoreMaximum`. Source: https://developerdocs.instructure.com/services/canvas/external-tools/lti/file.content_item
- Blackboard Learn supports LTI 1.3/Advantage and provides token endpoints for services such as Assignment & Grades and Names & Roles. Source: https://blackboard.github.io/lti/getting-started-with-lti
- Blackboard Learn accepts grades posted by external LTI tools into Grade Center columns created by tool placements. Source: https://help.blackboard.com/Learn/Administrator/Hosting/System_Integration/LTI
- Google Classroom API supports creating/updating coursework, add-on attachments, student submissions, rubrics, and grade updates. Sources: https://developers.google.com/workspace/classroom/reference/rest and https://developers.google.com/workspace/classroom/guides/classroom-api/manage-grades
- Blackbaud Education Management exposes OneRoster integrations where Blackbaud is the roster-data provider and assignment-grade recipient. Source: https://webfiles-sc1.blackbaud.com/files/support/helpfiles/education/k12/full-help/content/bb-core-oauth.html
- PowerSchool integrations often require admin-enabled OAuth/plugin credentials or partner pathways. Source: https://ps.powerschool-docs.com/enrollment/latest/powerschool-sis

## Goals

- Let students and teachers launch Yawp from an LMS without duplicate account friction.
- Read roster/class context so Yawp can map LMS courses/classes to Yawp classes.
- Let teachers place Yawp assignments in the LMS.
- Pass grades/points back to the LMS gradebook.
- Preserve Yawp's assignment-type/tutor/grading-assistant model.
- Keep per-assignment point value compatible with external gradebooks.

## Non-goals

- Supporting every LMS/SIS at once.
- Building a generic integration marketplace in v1.
- Replacing Yawp's class model with LMS classes before mapping behavior is proven.
- Depending on one vendor API when a standard path is available.

## Internal integration contract

Create a platform-neutral integration layer with these capabilities:

- `launchIdentity`: validates launch/auth and maps external user to Yawp profile.
- `courseContext`: maps external course/class/context to Yawp class.
- `rosterProvider`: reads students/teachers/enrollments.
- `assignmentPublisher`: creates or deep-links Yawp assignment launch items into the external platform.
- `gradePassback`: writes score/points/status back to LMS/SIS.
- `eventIngest`: receives webhook/event updates where available.
- `adminInstall`: stores tenant/deployment/client credentials and installation settings.

## Platform order

1. **Canvas LTI 1.3 Advantage MVP**
   - Best first target because Canvas has strong LTI and REST surfaces.
   - Scope: launch, course/user context, Deep Linking assignment placement, AGS grade passback, NRPS roster read.
2. **Blackboard Learn LTI 1.3 Advantage**
   - Good second target because Kevin's/UA context includes Blackboard and it proves portability beyond Canvas.
3. **Google Classroom API/Add-on**
   - Valuable for K-12, but OAuth review/Marketplace review and Classroom-specific API shape add overhead.
4. **OneRoster layer**
   - Supports roster ingestion and SIS-gradebook interoperability across districts and vendors.
5. **PowerSchool**
   - Treat primarily as SIS/gradebook integration, likely gated by partner/admin setup.
6. **Blackbaud**
   - Important for private K-12; likely needs pilot-school validation because permissions and gradebook conventions vary.

## UX sketch

Teacher install/setup:

```text
Admin settings
  Integrations
    Canvas / Blackboard / Google Classroom / PowerSchool / Blackbaud
    Status: not installed / installed / needs credentials / error
```

Teacher workflow:

```text
LMS course
  Add external tool / Yawp assignment
  Select Yawp assignment type
  Configure prompt, point value, due date
  Publish
```

Student workflow:

```text
LMS assignment
  Open Yawp
  Write/submit in Yawp
  Grade returns to LMS when released
```

## Data model implications

Add integration tables without replacing existing Yawp classes/assignments.

Likely new records:

- `IntegrationTenant`
  - provider, external tenant/domain, deployment/client IDs, encrypted credentials, status.
- `ExternalCourseMap`
  - provider course/context id -> Yawp class id.
- `ExternalUserMap`
  - provider user id -> Yawp profile id.
- `ExternalAssignmentMap`
  - provider line item/coursework id -> Yawp assignment id.
- `GradePassbackJob`
  - assignment/submission/external target, idempotency key, status, retry metadata, last error.

Backward compatibility:

- Existing Yawp classes and assignments stay canonical.
- Integration maps are additive.
- Grade passback only runs for mapped external assignments.
- If integration fails, Yawp remains usable without external sync.

## File paths in `yawp-2.0` likely to change

- `packages/prisma/schema.prisma` - integration mapping tables and encrypted credential references.
- `packages/prisma/migrations/...` - additive integration tables.
- `services/web-app/app/routes/api.integrations.*` - install/sync endpoints.
- `services/web-app/app/services/integrations/*` - provider-neutral contract and provider adapters.
- `services/web-app/app/services/integrations/lti/*` - LTI 1.3 launch, JWT/JWKS validation, AGS, NRPS, Deep Linking.
- `services/web-app/app/services/integrations/canvas/*` - Canvas-specific adapter if needed.
- `services/web-app/app/services/integrations/google-classroom/*` - Classroom API adapter.
- `services/web-app/app/services/integrations/oneroster/*` - OneRoster models/client.
- `services/web-app/app/routes/app.admin.integrations*/route.tsx` - admin setup UI.
- `services/web-app/app/routes/app._index/components/dashboard-create-assignment-sheet.tsx` - point value and publish-to-LMS hooks.
- `services/web-app/e2e/tests/integrations.*.spec.ts` - mocked provider flows.

## Open questions

- [ ] Which customer/pilot drives the first integration: Canvas school, Blackboard/UA, or Google Classroom K-12?
- [ ] Does v1 require grade passback, or is launch + roster enough for the first pilot?
- [ ] Should Yawp create external LMS assignments, or should teachers create LMS shell assignments that deep-link into Yawp?
- [ ] What is the exact grade release trigger for passback: GA completion, teacher override, or teacher release?
- [ ] How should Yawp handle classes with multiple teachers or co-teachers from LMS rosters?
- [ ] Should unmapped LMS users be auto-created, invited, or blocked pending admin review?
- [ ] For Google Classroom, do we pursue an add-on path immediately or start with standard Classroom API OAuth?

## Edge cases

- Teacher changes point value in Yawp after grades were already passed back.
- LMS assignment is deleted/archived while Yawp assignment remains active.
- Student opens Yawp outside LMS after being provisioned through LMS.
- Same student exists under different external IDs across systems.
- Teacher belongs to multiple organizations/tenants.
- Grade passback partially fails for a subset of students.
- LMS roster changes mid-assignment.
- External platform rate limits or rejects a grade update.

## Test plan

- Unit: LTI launch validation rejects bad issuer/audience/signature/nonce.
- Unit: integration contract maps external user/course/assignment IDs idempotently.
- Unit: point value maps to provider line-item max score.
- Unit: grade passback job is idempotent and retry-safe.
- Integration: mocked Canvas LTI launch creates/links a Yawp user/class.
- Integration: mocked Deep Linking response creates an external assignment link.
- Integration: mocked AGS grade passback sends points after teacher release.
- E2E: teacher launches from LMS, creates Yawp assignment, student submits, teacher releases, grade passback job succeeds.
- E2E: provider outage leaves Yawp grade intact and surfaces retry status to admin.

## Rollout

Feature flags:

- `feature_lms_integrations`
- Provider flags: `feature_lms_canvas`, `feature_lms_blackboard`, etc.

Staged path:

1. Internal mocked provider harness.
2. Canvas sandbox.
3. One real Canvas pilot or Blackboard/UA pilot, depending on customer access.
4. Add second LTI platform to validate abstraction.
5. Add Google Classroom or OneRoster based on sales priority.

## Engineering handoff checklist

- [x] Domain context covered
- [x] File paths in `yawp-2.0` listed
- [x] Data model implications spelled out, including backward-compat plan
- [x] UX sketch in prose
- [x] Edge cases enumerated
- [x] Test plan written
- [x] Rollout plan decided
- [ ] First pilot platform/customer selected
- [ ] Grade passback required-for-v1 decision made