WebmasterID logoWebmasterID
Architecture

Small surface, infrastructure-grade foundations.

WebmasterID is a pnpm + Turborepo monorepo with strong TypeScript everywhere. Each piece is purposely small and replaceable; nothing is magic. This page walks the system end to end.

The pieces

Six things the product is made of.

  • Browser tracker

    Small IIFE script (~3 KB minified) loaded from /tracker.iife.min.js. Auto-fires page_view on first paint, hooks history.pushState/replaceState/popstate for SPA navigation, and exposes a typed window.WebmasterID API.

  • Ingest API

    Fastify on Vercel functions. Validates events with Zod, classifies traffic source, detects AI/search bots, anonymises IP, and persists to Postgres. Accepts both application/json and text/plain.

  • PostgreSQL via Supabase

    Drizzle schema with separate events and bot_visits tables. wmsk_ secret keys are stored as SHA-256 hashes only. The plaintext is shown once at site creation and never again.

  • AI / search-bot detection

    Recognised crawlers (GPTBot, ClaudeBot, PerplexityBot, Google-Extended, Applebot, Bingbot, Meta-ExternalAgent, CCBot, …) route to bot_visits, never to events. Human aggregates stay clean.

  • Operator dashboard

    Server-rendered Next.js dashboard at webmasterid-dashboard.vercel.app. Site + range filter via URL params; six pages: Overview, Sites, Events, AI Visibility, Campaigns, Diagnostics.

  • Server-side events API

    POST /api/server/events accepts trusted server-to-server events with a Bearer wmsk_ token validated against its SHA-256 hash. Lets backends record events the browser would never see.

Transport

A quiet network path.

  • Why text/plain

    navigator.sendBeacon with a string body sets Content-Type to text/plain;charset=UTF-8, a CORS-safelisted MIME. No preflight, no credentialed-CORS surface, no negotiation with platform-level CORS layers.

  • Why same-origin tracker hosting

    The tracker is served from the marketing site's origin. Customers can self-host if they prefer; the install snippet is a single <script> tag with two data-* attributes.

  • Why anonymized IP

    IPv4 last octet zeroed, IPv6 truncated to /48. Enough resolution to detect bot waves and rough geography; not enough to identify a specific person.

  • Why no cookies

    WebmasterID has no concept of a returning visitor across sites. There is nothing the product would do with a cookie that it cannot do without one, so there is no cookie.

Install snippet

One script tag.

A WebmasterID install is a single <script> tag with two data attributes: data-wmid (your site_id) and data-endpoint (the ingest URL). The current snippet is on the homepage. Customer sites remain responsible for their own consent flow; WebmasterID does not wrap the tracker in a consent SDK by default.

The tracker file is hosted at https://webmasterid.com/tracker.iife.min.js and served with a 5-minute Cache-Control. It is the same artefact built from packages/tracker-js in this monorepo.

Where things live in code

Repository layout.

github.com/PetroTitan/webmasterid
/apps
  /web          — public marketing site (this site)
  /dashboard    — operator dashboard
  /ingest-api   — Fastify event ingestion

/packages
  /tracker-js       — browser tracker (IIFE + ESM)
  /sdk-next         — <WebmasterID siteId="wm_xxxx" />
  /database         — Drizzle schema (PostgreSQL)
  /shared           — types, Zod schemas, IDs
  /privacy          — IP anon, DNT, consent, retention
  /ai-visibility    — bot detection + AI referrals
  /seo-intelligence — search-engine + referrer classification
Read next

Related pages