PostHog

Build me a self-hosted web analytics box to replace PostHog. Requirements:

- One Node 22 + Express process with better-sqlite3, serving the collector and the
  dashboard on port 8787. No frontend framework, no build step, no Docker.
- A tracker.js I paste on my sites: pageviews on load and history change, plus
  window.track('signup', { plan: 'pro' }), POSTed to /e on my own domain so
  collection stays first-party.
- One SQLite events table: site, event, path, referrer, UTM fields, country from the
  proxy header, device class, and a JSON properties blob.
- Count visitors by a daily-rotating salted hash of IP plus user agent, salt in .env.
  No cookie, never the raw IP. That is the whole privacy design, keep it.
- Dashboard at / with a date range picker: visitors and pageviews by day, top pages,
  referrers, countries, any event split by one property, and a three-step funnel.
- Nightly rollup into a daily-summary table, raw events pruned past the retention
  window in .env, /export.csv for the raw rows.
- Basic auth on the dashboard, collector open. No accounts, no telemetry, my box
  holds the only copy.
- Out of scope: session replay, feature flags, and stitching one person across
  devices. Do not build a plugin system or a warehouse connector.
- README: the snippet to paste, where the SQLite file lives, and how to back it up.

# AGENTS.md — Build guide for PostHog

## Project scope
Collect first-party pageviews and custom events from your own sites, keep the raw rows yourself, and answer a handful of product questions from a local dashboard.

Catalogue verdict: no. First-party collection and a dashboard that answers your top five questions is one sitting of work, and PostHog's free tier covers a million events a month before you pay anything. What the bill buys past that is the rest of the platform: session replay, feature flags, SQL over years of events, and ingestion that stays correct while your event schema drifts underneath it.
Use the implementation prompt below to define the deliverable. Complete each phase's acceptance checks before extending the scope.

## Working agreement
- Inspect the repository and its existing instructions before choosing paths, dependencies or commands. Keep one coherent stack and explain changes to the proposed architecture.
- Plan a vertical slice that accepts a real input and produces the useful output described below. Persist only the state the prompt calls for; respect memory-only and upstream-managed workflows. Use fixtures only when they are clearly labelled.
- After scaffolding, document the actual install, development, check and build commands in README and keep them synchronized with the package or project manifest. Do not report commands as successful unless they ran.
- Work in small steps. At handoff, list implemented flows, checks actually performed, remaining blockers, and any credentials or provider setup the owner must supply.
- Do not publish, spend money, contact customers, delete source data or run irreversible migrations without the project owner's authorization.

## Prerequisites
- Node 22
- a small always-on VPS
- a domain you control, for first-party collection

## Stack and architecture
- One Node 22 + Express process with better-sqlite3, serving the collector and the dashboard on port 8787. No frontend framework, no build step, no Docker.
- Model data sources, dated observations, derived metrics, and report snapshots; keep stable source IDs and timestamps.
- Interface for this web and product analytics workflow: a local web page with input, progress, review, and export views.

## Security and data integrity
- On invalid input or interrupted processing, keep the original record, show the failed step, and permit a safe retry.
- Validate imported records and file paths; keep user data within the storage location named in the prompt.
- State the practical limit: session replay.

## Agent implementation rules
- Project rule, data: Model data sources, dated observations, derived metrics, and report snapshots; keep stable source IDs and timestamps.
- Project rule, behavior: One SQLite events table: site, event, path, referrer, UTM fields, country from the proxy header, device class, and a JSON properties blob.
- Project rule, recovery: On invalid input or interrupted processing, keep the original record, show the failed step, and permit a safe retry.

## Optional agent skills and references
No installable skill is listed for this guide; use the project rules and the stack documentation.

Read the linked SKILL.md and its dependencies before adding a skill. Select only the skills matching this project's runtime and task; their documentation does not supply API access, credentials or approval to perform external actions. Pin the reviewed revision where the tool supports it. Follow the chosen agent's documented project-level installation mechanism.

## Distribution ideas
These are optional planning notes. Obtain the owner's approval before publishing or contacting anyone.
- Demonstrate this web and product analytics operation with sample or user-owned data: One SQLite events table: site, event, path, referrer, UTM fields, country from the proxy header, device class, and a JSON properties blob.
- Show a concrete result or export: Nightly rollup into a daily-summary table, raw events pruned past the retention window in .env, /export.csv for the raw rows.
- State the practical limit: session replay.

## Engineering roadmap
1. Phase 1, architecture and data: One Node 22 + Express process with better-sqlite3, serving the collector and the dashboard on port 8787. No frontend framework, no build step, no Docker. Model data sources, dated observations, derived metrics, and report snapshots; keep stable source IDs and timestamps.
2. Phase 2, implement: One SQLite events table: site, event, path, referrer, UTM fields, country from the proxy header, device class, and a JSON properties blob.
3. Phase 3, implement: Dashboard at / with a date range picker: visitors and pageviews by day, top pages, referrers, countries, any event split by one property, and a three-step funnel.
4. Phase 4, review and output: Nightly rollup into a daily-summary table, raw events pruned past the retention window in .env, /export.csv for the raw rows.
5. Phase 5, recovery and acceptance: On invalid input or interrupted processing, keep the original record, show the failed step, and permit a safe retry. Verify this invariant with a saved fixture: A replayed batch cannot double-count events; missing or late data must be labelled in the report. State the practical limit: session replay.

## Paid-product capabilities outside this build
- session replay
- feature flags and experiments
- identity stitching across devices
- SQL over years of events
- ingestion that stays up without you watching it

## Implementation prompt
Build me a self-hosted web analytics box to replace PostHog. Requirements:

- One Node 22 + Express process with better-sqlite3, serving the collector and the
  dashboard on port 8787. No frontend framework, no build step, no Docker.
- A tracker.js I paste on my sites: pageviews on load and history change, plus
  window.track('signup', { plan: 'pro' }), POSTed to /e on my own domain so
  collection stays first-party.
- One SQLite events table: site, event, path, referrer, UTM fields, country from the
  proxy header, device class, and a JSON properties blob.
- Count visitors by a daily-rotating salted hash of IP plus user agent, salt in .env.
  No cookie, never the raw IP. That is the whole privacy design, keep it.
- Dashboard at / with a date range picker: visitors and pageviews by day, top pages,
  referrers, countries, any event split by one property, and a three-step funnel.
- Nightly rollup into a daily-summary table, raw events pruned past the retention
  window in .env, /export.csv for the raw rows.
- Basic auth on the dashboard, collector open. No accounts, no telemetry, my box
  holds the only copy.
- Out of scope: session replay, feature flags, and stitching one person across
  devices. Do not build a plugin system or a warehouse connector.
- README: the snippet to paste, where the SQLite file lives, and how to back it up.

## Completion evidence
Demonstrate the prompt's acceptance scenarios against the scoped workflow. Include setup from a clean checkout and failure recovery. Check persistence across restart and export/restore only for the state the prompt says to store; for memory-only tools, confirm that temporary content is discarded as specified. Record actual results and remaining limitations. A detailed plan alone does not establish a working replacement.