classroomio/prd/scorm-support/implementation-plan.md

# SCORM Support Implementation Plan

## Purpose

Translate the SCORM Support PRD into an engineering-first execution order that fits current ClassroomIO conventions.

## Delivery Order

1. Data model and package storage
2. Manifest parser and package ingestion
3. Lesson linkage model
4. Learner runtime shell
5. Runtime persistence APIs
6. Progress/certification integration
7. Reporting and diagnostics

## 1. Data Model

### Schema work

Add SCORM-focused tables and relations in `packages/db/src/schema.ts`:

1. `scorm_package`
2. `scorm_package_item`
3. `scorm_registration`
4. `scorm_attempt`
5. `scorm_runtime_event`

Add lesson linkage for SCORM-backed content.

### Query layer

Add pure query modules under:

- `packages/db/src/queries/scorm/package.ts`
- `packages/db/src/queries/scorm/registration.ts`
- `packages/db/src/queries/scorm/attempt.ts`
- `packages/db/src/queries/scorm/runtime-event.ts`

## 2. Validation and Contracts

Add validation modules under:

- `packages/utils/src/validation/scorm/package.ts`
- `packages/utils/src/validation/scorm/runtime.ts`
- `packages/utils/src/validation/scorm/report.ts`

Include:

1. package upload metadata
2. lesson attachment payloads
3. runtime commit payload
4. reporting query params

## 3. Package Ingestion Service

Add services under:

- `apps/api/src/services/scorm/package.ts`
- `apps/api/src/services/scorm/manifest.ts`
- `apps/api/src/services/scorm/storage.ts`

Responsibilities:

1. upload intake
2. safe unzip
3. manifest parse
4. package metadata persistence
5. warning generation

## 4. Runtime Service

Add services under:

- `apps/api/src/services/scorm/runtime.ts`
- `apps/api/src/services/scorm/registration.ts`

Responsibilities:

1. create/resume learner registration
2. commit runtime writes
3. finalize attempts
4. map SCORM state to ClassroomIO lesson completion

## 5. Routes

Add routes under:

- `apps/api/src/routes/scorm/package.ts`
- `apps/api/src/routes/scorm/runtime.ts`
- `apps/api/src/routes/scorm/report.ts`
- `apps/api/src/routes/scorm/index.ts`

Mount under a single root segment in `apps/api/src/app.ts`:

- `.route('/scorm', scormRouter)`

## 6. Dashboard

Add feature areas under:

- `apps/dashboard/src/lib/features/scorm/api/`
- `apps/dashboard/src/lib/features/scorm/components/`
- `apps/dashboard/src/lib/features/scorm/utils/`

UI work:

1. package upload modal
2. package detail view
3. lesson editor integration
4. reporting table and learner detail drawer

## 7. Learner Shell

Add a SCORM player surface in dashboard lesson rendering.

Potential locations:

- `apps/dashboard/src/lib/features/scorm/components/scorm-player.svelte`
- `apps/dashboard/src/lib/features/scorm/components/scorm-shell.svelte`

Responsibilities:

1. load launch target
2. expose `API` and `API_1484_11`
3. buffer/set runtime values
4. commit and terminate on lifecycle boundaries

## 8. Progress Integration

Update existing course completion and reporting logic to include SCORM-backed lessons.

Primary touchpoints:

- `apps/api/src/services/course/completion.ts`
- `packages/db/src/queries/course/content.ts`
- `packages/db/src/queries/course/course.ts`

## 9. Testing

### Unit

1. manifest parser
2. runtime data model mapping
3. completion mapping

### Integration

1. upload and parse endpoints
2. runtime commit endpoint
3. registration resume behavior

### Compatibility

Store representative fixture packages and run regression checks against:

1. SCORM 1.2 export
2. SCORM 2004 export
3. relaunch/resume flow

## Build and Verification

1. `pnpm --filter @cio/utils build`
2. `pnpm --filter @cio/db build`
3. `pnpm --filter @cio/api build`
4. `pnpm --filter @cio/dashboard build`

## Suggested First Sprint Slice

1. schema + queries
2. package upload + parser
3. lesson linkage
4. narrow runtime proof of concept for one SCORM 1.2 package