Skip to content
ulamsulamsulams docs

Developers

ulams is a headless LMS: a Laravel 13 API built from vendored packages, two small Node services (H5P and PDF), an Astro reference frontend with a framework-free SDK and UI catalogue, a React admin panel and a legacy React learner app, all in one Yarn and Turborepo monorepo. Start with the architecture, then set up the stack.

How it fits together

Section titled “How it fits together”
ArchitectureServices, hosts, request flow, workers and backing services.
Monorepo layoutFolders, workspaces, Turborepo tasks and shared libraries.
API packagesEvery package in api/packages, grouped by domain.
TenancyDatabase, bucket and keys per tenant; --domain; content origin; isolation tests.
AuthenticationPassport tokens, roles, demo login, LTI launches, how clients keep tokens.
API referenceSwagger UI, the generated spec, SDK types and the endpoint index.

Frontends

Section titled “Frontends”
Reference frontendfront/web (Astro SSR, BFF, H5P proxy), @ulams/sdk and @ulams/ui.
Generative UIPage documents, bindings, validation and fallbacks; AG-UI streaming to come.
Legacy learner appThe React app in front/src and the libraries the admin shares with it.
LLM layer and Course BuilderThe ai and course-builder packages, the AG-UI stream and the eval command.

Working on the code

Section titled “Working on the code”
Local developmentRun the API stack, the frontends and a tenant on your machine.
TestingPHPUnit suites, Vitest, Playwright, integration tests.
DebuggingLogs, Horizon, the database, the services.
PerformanceCaching, measuring and keeping pages fast.
CIWhat runs on every pull request.
Container imagesThe images we build and publish, and their licences.
OpenAPI and SDKAnnotating endpoints and regenerating SDK types.
Coding standardsConventions for PHP, TypeScript, commits and branches.

How-to guides

Section titled “How-to guides”
Adding an endpointRoute, controller, policy, permission, tests and tenant isolation.
Adding an admin screenA new page in the umi/max admin.
Adding a web pageA new page in front/web with the catalogue and the BFF.

Rules that apply everywhere

Section titled “Rules that apply everywhere”

Non-negotiables

  • LMS entities are changed through domain services, never by writing tables directly.
  • Every new endpoint gets a tenant isolation test; learner-facing UI meets WCAG 2.2 AA.
  • Uploaded content is untrusted input; third-party package code runs only on the content origin.
  • H5P stays in its isolated GPL service; no @lumieducation/* imports in MIT code.
  • Do not use or depend on escolalms/recommender.
  • Existing tests and linters stay green; H5P and SCORM behaviour does not change by accident.

Generated reference pages (packages, permissions, settings, environment variables, endpoints, events, artisan commands, scheduled jobs, UI catalogue) are rebuilt from the repository on every docs build. Decisions are in Decisions; contributing rules in Contributing.