flarelytics

Flarelytics is an open‑source web‑analytics project designed to measure the time visitors spend reading content on a website. It aims to provide a privacy‑respecting alternative to mainstream analytics services, which often collect extensive personal data or lack precise dwell‑time metrics. **Architecture** - **Browser script** (located in the `analytics` folder) – a small JavaScript snippet that website owners embed in their pages. It generates a UUID for each visitor session and sends two events to the backend: one when the page loads and another when the page is hidden or unloaded. - **Backend** (in `src`) – a TypeScript application deployed as a Cloudflare Worker. It exposes a simple HTTP API that receives the events and stores them in a PlanetScale MySQL‑compatible database. The backend also aggregates the raw events into per‑page dwell‑time statistics that can be viewed on a dashboard. **Key features** - Self‑hosted: run the worker on your own Cloudflare account and store data in your own PlanetScale database. - Privacy‑first: no third‑party tracking cookies, no IP logging, and all data stays under your control. - Single‑domain support (future versions may add multi‑domain handling). - Simple deployment workflow using `wrangler` and `pnpm`. **Development workflow** 1. Create free Cloudflare and PlanetScale accounts. 2. Clone the repo and install Node.js v18+, pnpm, and the PlanetScale CLI. 3. Set up a PlanetScale database named `flarelytics` with `main` and `dev` branches; use the `dev` branch for local work. 4. Create a Cloudflare Worker (e.g., `flarelytics-dev`) and store database credentials as secret environment variables. 5. Run `pnpm run setup-test-db` to create tables, then `pnpm run dev` to start a local worker. 6. Deploy with `npm run deploy-dev` when ready for a test environment. **Contribution** The project is maintained by the Google Developer Student Club at Budapest University of Technology and Economics. Contributors are encouraged to pick issues from the GitHub tracker, follow the standard fork‑branch‑PR flow, and adhere to the contribution guidelines outlined in the README. **Status** Flarelytics is under active development and not yet recommended for production use. Future plans include multi‑domain support, richer dashboards, and optional authentication for the analytics UI.