Browse the documentation
Developer and operations documentation
Technical documentation for Wintertrace: build your own modules and run the software yourself. A neutral reference, not sales copy.
The module system is available: a module registers its capabilities through a ServiceProvider in the core registries, without changing core files. This documentation describes the system as it actually exists today.
A public REST API is planned, but not yet available — it will get its own reference once it exists. These pages do not invent features that are not there yet.
Building modules
How to build your own modules for Wintertrace: the architecture, the lifecycle, the manifest, the ServiceProvider, and the registries a module uses to register capabilities — without touching core files.
- Quick start Build a working Wintertrace module from scratch — ServiceProvider, a navigation item, a dashboard widget, a route, settings and translations — step by step.
- Architecture How Wintertrace loads modules at boot and where a module plugs in: the registry-based extension model that lets modules add capabilities without changing core files.
- Lifecycle From discovery to boot to removal: how a module is found, registered, enabled, disabled and uninstalled, and what happens to its data at each step.
- Manifest (module.json) Every module is described by a module.json. The fields it must declare, what each one controls, and how the manifest drives discovery and compatibility.
- ServiceProvider The ServiceProvider is a module's single entry point. The register vs. boot phases, loading views and translations, and registering settings — with examples.
- Registries The core registries a module writes to — navigation, widgets, permissions, routes, notifications and more — with the exact API for registering each capability.
- Interfaces The contracts a module implements to be recognised by the core — what each interface guarantees and the methods you must provide.
- Events The domain events Wintertrace dispatches and how a module listens for them to react to shifts, tracks, reports and other actions.
- Filter hooks Filter hooks let a module transform values as they pass through the core. How to register a filter, what it receives, and what it must return.
- Template slots Inject or replace markup at defined points in core views from a module, using the slot registry — without editing core templates.
- Navigation & dashboard Add navigation items and dashboard widgets from a module: the registry calls, ordering, permissions and what a widget can render.
- Permissions & roles Register a module's own permissions and role templates so administrators can grant exactly the access your features need.
- Routes & APIs Add web and API routes from a module: the registrar, middleware, naming, and how module routes coexist with the core.
- Public homepage & SEO How a frontpage module serves a public homepage and opts specific pages into search-engine indexing — while the rest of the installation stays private and unindexed.
- Database & migrations How a module ships its own tables and migrations, runs them through the module lifecycle, and cleans up on uninstall.
- Assets & frontend Ship CSS and JavaScript from a module and have the core load them: where assets live, how they are published, and how they are referenced.
- Translations Provide translatable strings from a module: the namespaced lang files, how the ModuleManager loads them automatically, and how to reference keys.
- Notifications Send notifications from a module and register your own notification channels through the channel registry.
- Storage & backup Register storage backends and backup targets from a module so its data takes part in the core's storage and backup flow.
- Weather & scheduling Use weather data and register scheduled tasks from a module, including dispatch strategies that decide when work runs.
- PDF & reports Generate PDFs and reports from a module: hooking into the reporting pipeline and shaping the output.
- Diagnostics & logging Register diagnostic reporters and emit logs from a module so operators can see its health on the diagnostics page.
- Portal & dashboards Extend the customer portal and build custom dashboards from a module, including the registry calls and what each surface can render.
- Core data model The core entities a module builds on — the main models, how they relate, and the fields a module can rely on.
- Signing & distribution How modules are signed with libsodium and distributed as verifiable packages, and what that means when you publish your own.
- Example module A guided read-through of the bundled reference module, section by section, showing each extension point in a real, runnable module.
Self-hosting & operations
How to run Wintertrace yourself: technical requirements and the path to a working installation on your own web hosting.
- System requirements What Wintertrace needs to run on your own web hosting: PHP version, database, required extensions, and the one scheduled task that drives everything.
- Installation A concise operator reference for installing Wintertrace on your own web hosting: the order of steps, the public-folder principle, the cron job, and what to do after first setup.
- OwnTracks / GPS Connect a driver's phone as a GPS source via OwnTracks: what to install, how the connection is configured, and how tracks reach Wintertrace.
- Updates & cron What the single per-minute cron job does, how signed auto-updates work, and why no long-running background process is required.
- Data ownership & migration Where your data lives, how to export it, and how to move a Wintertrace installation to another server — you stay in control of the data the whole time.
The full source code is openly available on GitHub (AGPLv3). For the authoritative detail of any behaviour, the code is the reference.