Technical architecture

How Beam works on Cloudflare's edge

This page explains the full lifecycle: what runs in the browser, what is processed at the edge, what gets written to D1, and how Beam estimates unique visitors without cookies or persistent identifiers.

Request lifecycle

  1. 1. Browser loads the sub-2KB script from /js/beam.js.
  2. 2. Script sends page payloads to /api/collect via sendBeacon() with fetch fallback.
  3. 3. Worker validates payload size, site ownership, CORS, and per-IP rate limit (KV TTL window).
  4. 4. Worker enriches request with Cloudflare headers (country) and lightweight UA parsing (browser/device).
  5. 5. Sanitized row is written to D1 with UTC timestamp and queried by dashboard/public APIs.
  6. 6. Dashboard computes aggregates, channels, goals, and insights from the same UTC range helpers.

Data flow diagram

One request path from page load to decision-ready dashboard views.

Visitor Page beam.js script /api/collect validation + enrichment KV rate limit + short cache D1 pageviews + events tables Dashboard + Public Views queries, charts, insights

Privacy model

Beam is intentionally strict about what is and is not collected.

Collected

  • Pathname only (no full URL query/body)
  • Referrer, screen width, language, timezone
  • Country from Cloudflare header
  • Browser family and device type

Not collected

  • No cookies or localStorage identifiers
  • No raw IP addresses stored
  • No user IDs, emails, or personal profiles
  • No cross-site persistent tracking

Unique visitor estimation

Beam approximates daily unique visitors using non-PII tuples: date + path + country + browser + screen_width.

  • Daily reset: fingerprint components include date, so identifiers rotate every UTC day.
  • No identity graph: the model is for trend quality, not person-level tracking.
  • Tradeoff: counts are intentionally approximate to preserve privacy.

Performance characteristics

Layer Design choice Why it matters
Tracking script Sub-2KB, async, beacon-first delivery Minimal impact on Core Web Vitals and page rendering.
Collection worker Edge execution with simple payload schema Low latency ingestion close to visitors worldwide.
Storage/query D1 + indexed UTC time windows Predictable aggregate queries for dashboards and digests.
Protection KV rate limiting + payload size caps Guards write paths against burst abuse and oversized bodies.

Try the architecture in production

Run the same flow end-to-end using the public demo or your own site in under two minutes.

Open live demo Open setup guides Create free account