Track pageviews and custom events on any site with a tiny SDK, ingest them through a high-throughput API built for 10k RPS, and explore them in a clean dashboard. No cookies, no third parties, your data stays on your infra.
Documentation — quickstart, install guides, event tracking, how it works, SDK reference. Served at /docs when the frontend is running.
┌──────────┐ POST /track ┌─────────────┐ enqueue ┌─────────┐
│ Site + │ ───────────────▶ │ Ingestion │ ──────────▶ │ Redis │
│ SDK │ │ API (hot │ │ (BullMQ)│
└──────────┘ │ path, <5ms)│ └────┬────┘
└─────────────┘ │
▼
┌──────────┐ REST/queries ┌─────────────┐ writes ┌───────────┐
│Dashboard │ ◀──────────────▶ │ Analytics │ ◀───────── │ Worker │
│(Next.js) │ │ API │ │(enrich + │
└──────────┘ └──────┬──────┘ │ batch) │
│ └─────┬─────┘
▼ ▼
┌─────────────────────────────────────┐
│ TimescaleDB (Postgres) │
└─────────────────────────────────────┘
The hot path is deliberately thin: the ingestion endpoint validates, rate-limits, and enqueues — everything heavy (user-agent parsing, GeoIP lookup, batched DB writes) happens async in the worker.
| Directory | What it is |
|---|---|
sdk/ |
@akdevv/pulse — lightweight JS/TS SDK with a React hook. Published on npm. |
backend/ |
Express 5 API + BullMQ worker pipeline. Auth (JWT + refresh tokens), site management, event ingestion, analytics queries. |
frontend/ |
Next.js dashboard — auth, site management, and analytics charts (Recharts + shadcn/ui). |
frontend/content/docs/ |
The docs, as markdown. Rendered at /docs, readable signed out. |
- SDK: pageview + custom event tracking, no cookies, SPA route-change aware, React hook (
usePulse) - Ingestion: Redis-backed rate limiting, Zod validation, async enrichment (device via ua-parser, geo via MaxMind), batched TimescaleDB writes
- Analytics API: pageviews, visitors, top pages, referrers, devices, and geo breakdowns over time ranges
- Custom events: named events with properties, via
trackEventor adata-pulse-eventattribute, with per-property breakdowns - Ask box: a plain-English question becomes validated read-only SQL over two site-scoped views, run as a restricted Postgres role
- Dashboard: multi-site support, per-site analytics views, dark mode
- Testing: Vitest unit/integration suite + Artillery load-test scripts (
backend/tests/load/)
Backend — Node.js, Express 5, TypeScript, Prisma 7, TimescaleDB, Redis + BullMQ, Zod, Docker Frontend — Next.js, React Query, Tailwind, shadcn/ui, Recharts SDK — zero-dependency TypeScript, tsup build, dual vanilla/React entry points
Requires Node ≥ 22, pnpm, and Docker.
# One-time setup
(cd backend && cp .env.example .env && pnpm install)
(cd frontend && cp .env.example .env && pnpm install)
# Then two commands, one per terminal.
# The backend one starts TimescaleDB + Redis in docker, runs migrations,
# then the API and worker together.
pnpm --dir backend dev
pnpm --dir frontend devThen follow the quickstart — or read it at /docs once the frontend is up.
Drop the SDK into any site:
import { Pulse } from "@akdevv/pulse/sdk";
Pulse.init({
siteId: "your-site-id",
apiHost: "http://localhost:8000",
});Core pipeline (SDK → ingestion → worker → TimescaleDB → dashboard) works end-to-end locally. Remaining plan (see notes/next-steps.md):
- AI-powered queries — natural language → validated SQL over your analytics data (see
notes/ai-query.md) - Custom event tracking —
trackEvent,data-pulse-event, property breakdowns - Docs at
/docs - Public demo site wired to the live backend
- Sustained load test (Artillery scripts in
backend/tests/load/; k6 for the real run) - Load-test case study write-up
MIT