Skip to main content

Architecture

Lernkit captures non-obvious design decisions as ADRs (Architecture Decision Records) using the MADR format. The records live in docs/adr/ at the repo root and are mirrored here on every build by a small custom Docusaurus plugin.

Reading the ADRs​

  • All ADRs — the full list with one-line summaries.
  • Each ADR keeps its number; renames preserve the ADR-NNNN suffix in URLs.
  • ADRs aren't versioned with the docs site; they describe decisions made at a point in time and are amended in place when superseded.

Quick reference: structural ADRs​

These are the decisions that shape how lernkit is built, not just what features it has:

  • ADR 0001 — Use MADR for ADRs.
  • ADR 0002 — Astro + Starlight + MDX + React islands.
  • ADR 0003 — Standards strategy: cmi5 first, SCORM 1.2 today, SCORM 2004 opt-in.
  • ADR 0004 — The Tracker interface.
  • ADR 0005 — scorm-again as the canonical LMS-API wrapper (legal-memo gated).
  • ADR 0014 — MIT license for the framework core.
  • ADR 0015 — One source, many outputs: the build-pipeline shape.
  • ADR 0022 — OSS single-tenant framework scope.

Quick reference: feature ADRs​

  • ADR 0006 — Pyodide in a Web Worker for in-browser Python.
  • ADR 0009 — Reuse rf-mcp as the RF runner base.
  • ADR 0010 — CodeMirror 6 as the editor.
  • ADR 0024 — Pyodide-RF for non-browser lessons.

Repo layout​

lernkit/
├── apps/
│   ├── api/              # backend services (future)
│   ├── docs/             # rf-training course site (Astro/Starlight)
│   └── website/          # this site (Docusaurus)
├── packages/
│   ├── components/       # @lernkit/components — quiz widgets
│   ├── config/           # @lernkit/config — shared tsconfig
│   ├── packagers/        # @lernkit/packagers — SCORM 1.2 (today)
│   ├── runtime/          # @lernkit/runtime — browser runtime helpers
│   └── tracker/          # @lernkit/tracker — Tracker interface + adapters
├── docs/
│   ├── adr/              # architecture decisions (single source of truth)
│   ├── plan/             # phase plans, risk register, etc.
│   └── research/         # exploratory deep dives
└── …

Build dependency graph​

@lernkit/config  (tsconfig only, no build artifacts)
       ↑ extended by all
       │
@lernkit/tracker  ← @lernkit/components → @lernkit/packagers
                                                    ↑
                              apps/docs ────────────┘ (uses packageScorm12)

apps/website (this site) depends on the source TSDoc of packagers and tracker via TypeDoc, but not on their built output.

Where to go next​