adityaboghara/better-moodle

1. What this repo is

Better-Moodle is a client-side userscript that runs in the browser on Moodle pages. There is no central backend for the product itself; the script injects UI, patches page behavior, and stores user preferences locally.

2. Top-level runtime split

The main runtime is under src/, with a small set of entrypoints like core.tsx, cleanupStorage.ts, migrateStorage.ts, and unsupportedBrowserCheck.tsx. The core runtime is what users normally get; the other entrypoints handle storage maintenance and browser compatibility warnings.

3. Core orchestration

src/core.tsx is the bootstrapping layer. It ties together feature registration, university-specific configuration, i18n, settings, update checks, and global fixes before individual features run. src/core/globalFixes contains patches that apply broadly across Moodle, independent of a specific feature toggle.

4. Feature-based architecture

Most functionality is organized as independent modules in src/features/*. Each feature is typically self-contained, with its own entry file, styles, and often its own translations. This lets the build include only the features relevant to the selected university/configuration and lets users enable/disable them from settings.

5. Shared UI and infrastructure

src/_lib holds the common building blocks: reusable React components, drawers/modals, settings controls, DOM helpers, network helpers, storage wrappers, template helpers, and Moodle-specific string/semver/time utilities. This is the internal platform layer that features build on.

6. State and persistence

User preferences and migration logic are handled through TempStorage, migrateStorage.ts, and cleanupStorage.ts. The script persists settings in browser storage, migrates older data formats, and can clean up obsolete keys. That means feature state lives entirely on the client side.

7. University-specific boundaries

The repo is clearly split by institution. configs/ contains per-university and global JSON config, while src/fixes/cau and src/fixes/uzl contain institution-specific fixes. The README also shows separate distributed builds/downloads for CAU Kiel and Universität zu Lübeck, so the build output is university-targeted rather than one generic bundle.

8. External Moodle integration

The types/require.js tree shows strong coupling to Moodle’s AMD/RequireJS modules and templates. Better-Moodle does not replace Moodle; it extends it by consuming Moodle’s internal modules, DOM structure, and templates, which is why those ambient typings are a major architectural boundary.

9. Localized content and templating

src/i18n contains the language packs and formatting helpers, while many feature folders also have their own i18n subtrees. Mustache templates and SCSS modules are used where features need Moodle-compatible markup or scoped styling. The result is a localized, theme-aware userscript rather than a single-language overlay.

10. Feature-specific external data flows

Some features integrate third-party or campus services. Examples include weather providers (open-meteo, openweathermap, visualcrossing, wttr.in), canteen/menu parsing, NINA emergency integration, and event/semester data from data/*.json. These modules adapt external data into the script’s UI and settings model.

11. Auxiliary parser/runtime

The ics-parser/ directory is a separate TypeScript worker-style component with its own Wrangler config. It indicates a distinct parsing runtime for calendar/ICS-style data, separate from the browser userscript bundle.

12. Build and distribution pipeline

The repo uses a custom Vite-based toolchain in tooling/ to assemble the userscript, resolve features/fixes, process SCSS and Mustache, inject legacy/polyfill behavior, and format post-build output. Release automation is handled via GitHub Actions and Release Please, which produce the downloadable .user.js artifacts referenced in the README.

13. Testing and quality gates

Tests live under __tests__ and use Vitest plus browser-oriented helpers/Puppeteer. CI workflows cover build, test, config validation, icon generation, release automation, and download tracking, so the repository is structured as a packaged extension-like artifact with strong build-time verification.