Build Plausible

The build, in order

1. 1

   Identity without cookies

   hideshow

   The visitor hash and its salt, done exactly right, before anything else exists.

   1. 1.1Create the project and the salts table

      salts (day, salt, created_at). Generate 32 random bytes per UTC day on first use.

      Files server.mjsidentity.mjs

      terminalcopy

      mkdir analytics && cd analytics && git init && npm init -y && npm pkg set type=module
      mkdir data public && cp .env.example .env

   2. 1.2Implement visitorHash(site, ip, userAgent)

      sha256(daily_salt + site_domain + ip + user_agent). Include the domain so the same visitor on two of your sites is two hashes. The ip and user agent exist only inside this function.

   3. 1.3Rotate and delete

      At UTC midnight create tomorrow's salt and delete yesterday's row. Deleting is what makes cross-day re-identification impossible even for you.

   done when · tick each as it passes

   • Two calls with the same ip and agent on the same day produce one hash
   • The same pair on two site ids produce two hashes
   • After a forced rotation the hash changes and the old salt row is gone
   • grep of the database file for your own IP returns nothing

   next phase
2. 2

   Ingest endpoint

   hideshow

   POST /api/event stores derived facts only and never makes a visitor's page wait.

   1. 2.1Create the events table with its indexes

      events (id, site_id, name, path, referrer_host, screen_class, country, browser, os, visitor_hash, session_id, timestamp). Index (site_id, timestamp) and (site_id, path, timestamp).

   2. 2.2Derive, then discard

      Screen class from a width the tracker sends, browser and os from the user agent, country from the GeoLite2 lookup. Strip query strings and hashes from path. Then drop the inputs.

   3. 2.3Always answer 202 with an empty body

      Unknown site ids are accepted and dropped. Malformed bodies get 202 too. Cap the body at 2 KB. An analytics endpoint must leak nothing about itself.

   done when · tick each as it passes

   • A hand-crafted curl writes one row with no raw identifiers
   • An unknown site_id returns 202 and stores nothing
   • A malformed body returns 202 without a stack trace in the log
   • Country resolves for a known public IP when GEOIP_DB_PATH is set

   next phase
3. 3

   The tracker

   hideshow

   Under 2 KB, no cookies, counts SPA route changes once, honours opt-out.

   1. 3.1Write public/p.js

      On load send a pageview with path, referrer and innerWidth via navigator.sendBeacon with a fetch fallback. Hook pushState and popstate for SPA routes. Expose window.plausible-style track(name) for custom events.

   2. 3.2Respect Do Not Track and a localStorage opt-out flag

      If either is set, send nothing at all.

   3. 3.3Serve it with a long cache header and a version in the filename

      p.v1.js; bump on change.

   4. 3.4Add the snippet to one real site and watch events arrive
      terminalcopy

      <script defer data-site="yoursite.com" src="https://stats.yourdomain.com/p.v1.js"></script>

   done when · tick each as it passes

   • The minified file is under 2 KB
   • One page load records exactly one pageview, including under React strict mode
   • An SPA route change records a second pageview
   • With the opt-out flag set nothing is sent

   next phase
4. 4

   Sessions and bounce rate

   hideshow

   Sessionize at write time so the dashboard never does it.

   1. 4.1Create the sessions table

      sessions (id, site_id, visitor_hash, started_at, last_event_at, entry_path, exit_path, event_count, is_bounce).

   2. 4.2Join or open a session on each event

      If the visitor's last event on this site was under 30 minutes ago, update that session; otherwise open a new one. A session with one pageview is a bounce.

   done when · tick each as it passes

   • Two pageviews 5 minutes apart are one session with is_bounce false
   • Two pageviews 31 minutes apart are two sessions, both bouncing
   • Bounce rate matches a hand count on a seeded fixture

   next phase
5. 5

   Bot filtering

   hideshow

   Drop obvious bots at ingest and count what you dropped.

   1. 5.1Filter by user agent and impossible screen classes

      A short bot list, plus events with no referrer and a zero width.

   2. 5.2Count filtered events in a separate table

      filtered (day, site_id, reason, n). A traffic drop you can explain beats one you guess at.

   done when · tick each as it passes

   • A curl with a default user agent is filtered
   • A real browser is not
   • The filtered count is visible on the dashboard

   next phase
6. 6

   Dashboard

   hideshow

   Every panel one indexed query; every number reconcilable with SQL.

   1. 6.1Build /dashboard behind basic auth with a site switcher

      Unique visitors, pageviews, bounce rate and visit duration for today, 7 and 30 days.

   2. 6.2Add top pages, referrers, countries, browsers, devices

      Each a GROUP BY with a LIMIT.

   3. 6.3Draw visitors per day as inline SVG

      No chart library. Dark mode.

   4. 6.4Seed 100,000 events and time every panel
      terminalcopy

      node scripts/seed.mjs 100000

   done when · tick each as it passes

   • Every number reconciles with a hand-written query on the seeded fixture
   • The page renders in under 200 ms on 100,000 events
   • Switching sites changes every panel

   next phase
7. 7

   Retention and deploy

   hideshow

   Old events rolled up, live on your domain, documented with the ceiling stated.

   1. 7.1Write the nightly rollup

      daily (day, site_id, visitors, pageviews, bounces) computed from events, then delete events older than RETENTION_DAYS. Charts read daily for old ranges.

   2. 7.2Add /healthz, systemd, Caddy and a backup command

      Files deploy/analytics.serviceCaddyfile

   3. 7.3Write the README and the data policy

      The snippet, a plain-language policy (collected, derived, never stored, salt deleted daily), and the traffic ceiling as a number.

      Files README.mdPRIVACY.md

   done when · tick each as it passes

   • Retention runs without breaking historical charts
   • A reader goes from clone to a tracked site using only the README
   • PRIVACY.md states that the daily salt is deleted

   next phase