{"path":"README.md","content":"# cf-d1-queues-pulse\n\nEvent analytics on Cloudflare. It shows **Queues** (producer, batched consumer, retries, dead-letter queue) feeding **D1** rollups, with an \"Oscilloscope\" dashboard of hand-drawn SVG charts.\n\n[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/nexarq-ai/cf-d1-queues-pulse)\n\n## What it shows\n- Totals (5 min / 1 h / 24 h), events per minute, top types and paths, countries, p50/p95 of `value`, consumer lag, batches processed; auto-refresh every 3 s with pause.\n- A browser load generator (rate, duration, type mix, poison %).\n- A dead-letter page (`/dlq`) to list, replay and purge failed messages.\n\n## Architecture\n```mermaid\nflowchart LR\n  B[Browser] -->|POST /api/events| W[Worker]\n  W -->|sendBatch| Q[(pulse-events)]\n  Q -->|batch up to 100| C[Consumer]\n  C -->|one batch upsert| D[(D1 rollups)]\n  Q -.retries exhausted.-> DLQ[(pulse-events-dlq)] --> X[DLQ consumer] --> D\n  B -->|GET /api/stats, /api/dlq| W\n  W --> D\n```\nSee [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) and [docs/API.md](docs/API.md).\n\n## Local development\n```sh\nnpm install\nnpm run dev\nnode scripts/load.mjs http://localhost:8787 50 10   # base URL, events/s, seconds\n```\nApply migrations locally with `npx wrangler d1 migrations apply pulse --local` (use the `database_name` in wrangler.jsonc).\n\n## Tests\n`npm test` (Vitest, Node environment) and `npm run typecheck`.\n\n## Deploy\n`npm run deploy:staging` or `npm run deploy`. `database_id` is intentionally omitted from wrangler.jsonc so Gitflare Deploys / Wrangler provisions the D1 databases. Staging and production use distinct database names. Apply migrations with `wrangler d1 migrations apply <database_name> --remote`.\n\n## Configuration\n| Item | Value |\n|---|---|\n| Queue `pulse-events` | batch 100, timeout 2 s, 3 retries |\n| DLQ `pulse-events-dlq` | consumed into D1 `dead_letters` |\n| D1 binding | rollups, samples, dead letters, consumer stats |\n| Cron | hourly, deletes rollups older than 7 days |\n| `POST /api/events` | up to 100 events per request |\n\n## Costs\nQueues, D1 and Workers have free tiers; Queues needs the Workers Paid plan at the time of writing. Each event costs about 3 queue operations; D1 writes are one batch per consumer batch, not per event. Check current Cloudflare pricing.\n\n## Screenshots\nAdd screenshots of the dashboard (dark and light) under `docs/`.\n\n## Built with Gitflare\nBuilt by coordinated agents in Gitflare, with tests verified on every change.\n\n## License\nApache-2.0, see [LICENSE](LICENSE).\n","commitSha":"8a65841ca84dd7d76da72f1b10cddfee27014bbe"}