Skip to content

ADR 0050

github-actions[bot] edited this page Nov 22, 2026 · 1 revision

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.

Analytics is our own contract; Spotless collects, Umami stores

Context

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.

Decision

  • The contract is ours (docs/contracts.md, Analytics): config.json with enabled and mode, the tracker at /_spotcraft/s.js with spotless.track() and the spotless.disabled off switch, and POST /_spotcraft/e taking 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-Site and the visitor's address in X-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.json keeps websiteId, and the tracker honours umami.disabled and offers window.umami.track. The next minor release drops them.

Consequences

  • 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).

Clone this wiki locally