@lms-assessment/core

A scalable, offline-first, open-source React assessment engine designed as a plug-and-play micro-frontend module for Learning Management Systems (LMS). Built exclusively with MIT/Apache 2.0 licensed libraries. No proprietary dependencies.

Repository Structure

assessment-engine/
├── packages/
│   ├── core/          # The npm package — the engine itself
│   └── demo/          # Vite + React demo application
├── docs/              # Architecture and implementation docs
├── CLAUDE.md          # Agent instructions (read first)
└── README.md          # This file

Quick Start

# Install dependencies (requires Node 18+)
npm install

# Run the demo app
npm run dev

# Run tests
npm test

# Build the core package
npm run build

Features

• Offline-first — IndexedDB/Dexie.js + Service Worker (Workbox) caching
• Rich content — PlateJS AST, KaTeX math/chemistry, Excalidraw diagrams
• Plugin system — Typed HostAPI, lazy import() loading, sandboxed lifecycle
• LTI 1.3 — OIDC/JWT, AGS grade passback, Deep Linking, NRPS
• White-label — Runtime CSS variable theming from JSON config
• Session integrity — Tab-switch detection, fullscreen enforcement, auto-submit
• Idempotent sync — UUID v4 Idempotency-Key, OCC with If-Match, 409 merge

Documentation

Start here

| File | Purpose | |------|---------| | docs/getting-started.md | First stop — install, render your first assessment, handle submissions | | docs/data-model.md | Questions, sections, assessments, and the Slate AST prompt format |

Deep dives

| File | Purpose | |------|---------| | docs/components.md | Every exported component, all props, CSS class reference | | docs/hooks.md | useAssessmentStore, useOfflineStatus, useAssessmentTimer, useProctoringSession | | docs/plugins.md | Built-in plugins, the HostAPI contract, writing custom question types | | docs/store.md | Zustand store shape, all actions, data flow diagram | | docs/sync.md | Offline storage, SyncEngine, idempotency keys, server endpoint spec | | docs/proctoring.md | Session integrity, extending violations, fullscreen enforcement |

Reference

| File | Purpose | |------|---------| | docs/architecture.md | Full system design and subsystem breakdown | | docs/requirements.md | Functional and non-functional requirements | | docs/schema.md | JSON Schema v7 reference for assessment data | | docs/plugin-api.md | Plugin HostAPI contract and lifecycle (technical reference) | | docs/sync-strategy.md | OCC, idempotency, and conflict resolution (technical reference) | | docs/lti-integration.md | LTI 1.3 Advantage setup guide | | docs/setup.md | Local development setup and troubleshooting |

Tech Stack

| Layer | Library | License | |-------|---------|---------| | UI | React 18 + TypeScript | MIT | | Rich Text | PlateJS + Slate.js | MIT | | Math | KaTeX + mhchem | MIT | | Diagrams | Excalidraw | MIT | | Markdown | Remark + Rehype | MIT | | State | Zustand | MIT | | Storage | Dexie.js (IndexedDB) | Apache 2.0 | | SW Cache | Workbox | MIT | | Sanitize | DOMPurify | Apache 2.0 | | Build | Vite + tsup | MIT | | Tests | Vitest + Testing Library | MIT |