Repository navigation
ADR 0050
Status: accepted · Built: done · Date: 2026-11-22
Partly supersedes 0038: the tracker and the collect endpoint's payload are no longer Umami's. The ecosystem's ADR 0007 (no lock-in). Built: kodentuzo/spotless 0.1.0, run as the spotless service; Caddy routes s.js and e to it with the site and client address headers; Umami's path renames are gone. For one release: config.json keeps websiteId, and the tracker honours umami.disabled and offers window.umami.track.
ADR 0038 put Umami on the instance and routed its tracker and collect
endpoint to every app domain. That made Umami's script, its event payload and its website id the
contract: an app or a native client written for it could only ever talk to Umami. Inside the agent,
Umami was already behind an Analytics interface; only the public side was locked to it.
-
The contract is ours (
docs/contracts.md, Analytics):config.jsonwithenabledandmode, the tracker at/_spotcraft/s.jswithspotless.track()and thespotless.disabledoff switch, andPOST /_spotcraft/etaking our JSON event, with identifying keys refused. -
Spotless (kodentuzo/spotless) implements it: a
small service with no runtime dependencies and no state. Caddy names the app's site in
X-Spotcraft-Siteand the visitor's address inX-Spotcraft-Client-IP; Spotless checks the event and hands it to its store. - Umami stays the store, behind Spotless's one-method backend interface. Its tracker and collect endpoint are no longer reachable from app domains.
-
For one release, pages written for Umami keep working:
config.jsonkeepswebsiteId, and the tracker honoursumami.disabledand offerswindow.umami.track. The next minor release drops them.
- Another store, or another collector that answers the same paths, can replace either half without touching an app.
- One more container on the instance, about 30 MB of memory.
- spotkit 0.4.0 follows the contract (no
websiteId, the new off switch,spotless.track).
Published from docs/. Edit the files there; changes here are overwritten.