Simple Analytics

Promptfree, for everyone, and the only version there is

Copy the prompt for Claude CodeCopy the prompt for CodexCopy the prompt for Cursor

Copy

Build me analytics that replace Simple Analytics: four numbers, no cookie, no personal data, and a bot list that makes the numbers real.

STACK
- Node 20+ with Fastify
- SQLite through better-sqlite3, WAL mode
- A tracking script under 2KB gzipped, from my own domain
- Server-rendered dashboard, charts as inline SVG drawn by hand
- Caddy in front

THE DATA MODEL
- sites: id, domain, name, timezone, salt, is_public, public_token
- pageviews: id, site_id, path, referrer_host, referrer_url, utm_json, country, lang, device, browser, os, screen_bucket, status, visitor_hash, session_id, is_entry, is_exit, duration_ms, bot, bot_reason, prefetch, created_at
- events: id, site_id, name, path, props_json, value_num, visitor_hash, bot, created_at
- goals, conversions
- bot_rules: id, kind, pattern, source, added_at — the list, as data, updatable without a deploy
- Record more than you publish. A signal not captured today starts from zero the day somebody wants it

THE BOT LIST, WHICH IS MOST OF THE DIFFERENCE
- The gap between a real number and a flattering one is almost entirely bot filtering. This is where the effort goes
- Flag, never drop, with the reason recorded, and exclude through a SQL view so the filtering lives in one place
- Four independent signals, each recorded separately:
  - the user agent, matched against a maintained list of known crawlers, monitors and libraries
  - whether the tracking script executed at all, which is the strongest humanity signal available and is why a script-based collector reports lower and truer numbers than a server log
  - behaviour: no referrer, one page, zero time, and arrival intervals too regular to be a person
  - the network: known datacentre ranges, if you have a local list
- Referrer spam is its own category — hosts appearing in your referrers purely to make you visit them. Keep a block list and count them separately rather than letting them into 'top sources'
- The dashboard can show bot traffic deliberately, because 'how much of that spike was a crawler' is a real question with a real answer
- Update the list on a schedule from a public source, and record which version was in force, so a change in the numbers is explicable rather than mysterious

NO COOKIE
- visitor_hash is HMAC-SHA256 of address, user agent and a per-site salt rotating daily; the inputs are discarded immediately
- Nothing written to the visitor's browser. No cookie, no storage, no fingerprint
- Daily rotation means 'visitors today' is exact and 'visitors this month' is an estimate — say so beside the number, every time
- Carry the previous salt for a grace period so a session across the rotation is not double-counted
- Nothing sent to any third party, ever

THE FOUR QUESTIONS
- The product being replaced is bought because it answers four things on one screen: how many people, which pages, where they came from, and what they did. Build exactly that
- Headline numbers, one chart over the chosen window, then pages, referrers, countries, devices and goals as tables
- Everything filterable by everything, with a comparison against the previous period
- Definitions written next to the numbers, because everybody computes bounce rate differently and a number without a definition is decoration
- Resist a second page. The restraint is the product

PREFETCHES, REDIRECTS AND WHAT COUNTS
- Prefetches and prerenders identified from request headers and excluded from views. Turning on link prefetching must not triple your traffic overnight
- Redirects do not count; only a 2xx GET is a page view
- A HEAD from an uptime monitor is answered, not read
- Static assets never counted

PUBLISHING YOUR OWN NUMBERS
- A public dashboard per site at a token URL, read-only, optionally password-protected
- Publishing your numbers openly is a small act of credibility, and if they are ever quoted to anybody — a sponsor, a client — every figure must be explainable in one sentence

COLLECTION
- The endpoint answers 204 in a couple of milliseconds and writes after responding
- Country from a local database file. Never an external geolocation API
- A fallback for blocked scripts: an image beacon, or the reverse proxy's log, marked as a different source

OPERATIONS
- .env: DATABASE_PATH, BASE_URL, HASH_SALT, GEOIP_DB_PATH, SESSION_SECRET, BOT_LIST_URL
- Migrations on boot, each once
- Nightly backup off the machine, restore script
- Health endpoint

WHAT MATTERS MOST
The bot list and the definitions. Build collection, the four signals and the excluding view before the dashboard exists, then compare a week against the raw access log and account for every difference. That reconciliation is the entire exercise — analytics you cannot defend in a sentence are worse than none.

Give me the repository, the tracking script, the bot list updater, migrations, .env.example, and a README with deploy steps behind Caddy and every definition written out.