HiLMS Developer Book

How HiLMS is built and how to extend it. Written for developers. Describes the current state of the system only; SPECS.md is the terse reference, this book explains.

HiLMS is MIT-licensed throughout — the application and every module, with the LICENSE file at the root — and so is the PHP SDK for its API. The WooCommerce plugin that sells access through that API is proprietary.

Chapters

1. Getting started — run the project locally in ten minutes.
2. Architecture — stack, modular monolith, module direction, request flow, the data model.
3. Modules and generators — anatomy of a module, hilms:make-*, everyday generators, seeding.
4. Conventions — code style, attributes, translations, Eloquent guard rails, Filament patterns, permissions, tests.
5. Access module — users, roles, Fortify, two-factor and passkeys, profile fields, provisioning, deletion, impersonation.
6. Catalog module — categories, courses, sections, lessons, the panel editors, the course page, its rail and where a student stands, the two listing blocks.
7. Quality — the four gates, tests on both engines and the guards on them, the caches the suite never reads, sub-trees, static analysis, CI, the guard tests.
8. Environment — the servers Lando runs, the host wrappers over them, the caches each side reads, sub-trees, builds, environment variables, troubleshooting.
9. Theming — the headless core, the shell and its contract, the reading width, the video player, the default theme, client themes, the contract, upgrades; the tokens (24) and the styles laid over them (25) have chapters of their own.
10. Blocks — the block kernel, containers, contexts, the three rules, files from the library, rendering, patterns, hilms:make-block.
11. Learning — entitlements versus enrolments, the actions that alone may write them, the player, where a student stands, course material, the quiz, a student’s own courses.
12. Pages — pages an editor owns, the destinations the application links to, templates, the fallback route, reserved slugs, starter content.
13. API and agents — /api/v1 on Passport, scopes, the SDK and the plugin, the MCP authoring server.
14. AI assistants — settings and providers, cost controls, the generation chain, the four assistants, adding one.
15. Operations — queues, the schedule, monitoring, health, backups, the audit trail, mail, media storage, the installer, the upgrade and the container that chooses between them.
16. Security and privacy — headers and the CSP, uploads, files from a web address, course material, the watermark, secrets, personal data, retention.
17. Accessibility — the target, the rule contract, the skeleton, colour and contrast, forms, live regions, media, the tooling, writing an accessible theme.
18. Languages — the list an installation speaks, prefixed addresses, translation groups, translated fields, the phrase editor, a language per person.
19. Navigation — menus per place and per language, link sources, the cached snapshot, audiences, the builder and its guards.
20. The block editor — the canvas, the settings panel, the picker, patterns, choosing a file, duplicate, the outline, and what a refused save says.
21. Time and clocks — UTC in every column, the installation’s clock and the person’s, the panel, <x-ui.date>, the wire, the traps.
22. Media — storage, the library and serving: assets and their uses, who sees what, the read-only view page, disks and buckets, addresses, the access check, moving files, adding a block or a model that shows files.
23. Settings — the one Settings cluster: groups and order, SettingsSection and InSettings, adding a section with hilms:make-settings, adding an option, secrets, the overview and its search, the guard tests.
24. Design tokens — tokens.json in the Design Tokens Format, tiers and lengths in steps, the model that reads it, the sheets generated from it (the site’s and the panel previews’), changing and adding a token, a theme’s own tokens, proving nothing moved with npm run visual, the traps.
25. Styles — what an administrator lays over the theme: what a style holds, compiling, why its sheet outranks the theme and never a person’s preferences, proving it with npm run cascade, serving it for free, activating and the accessibility switch, previewing, built-in styles, the editor, import and export, fonts from the catalogue and from uploads, mail in the style’s colours, recipes and traps.
26. Components, looks, options and generators — the words of the styles track, component tokens and adding one, a block’s look and its own default look, the options and variants a theme leaves to a style, generating a style from five answers, and what a theme without a build cannot do.

These books are also a site, published at hilms-docs.higreg.pl: docs/ is a Starlight project that reads the chapters where they are. To write in them, give a new chapter a frontmatter title instead of a # line and link other chapters as relative .md files, as GitHub reads them; the build rewrites those links for the site and fails on any link or heading anchor that leads nowhere. npm --prefix docs run dev previews it, npm --prefix docs run build builds and checks it, and npm --prefix docs run deploy ships it to vps1 (deploy:dry first). A change under docs/ keeps a bin/gates pass, except to a chapter a test reads. Beside the books, the How-to guides take one developer’s task from the first command to the last check.

The operator’s documentation lives beside this book in docs/install/: requirements, Docker, manual installation, upgrading, media storage, theming, languages, MCP, retention and social login.