Clutch Darts

A darts player practising alone has no way to tell whether they are actually improving. A three-dart average written in a notebook does not answer whether your checkout percentage is better than last month, or whether you only ever win against the bot. Players were coping with paper and spreadsheets, which nobody sustains long enough to see a trend. On top of that, "I'll practise three times a week" fails silently — there was nothing tracking whether you actually showed up.

The app is offline-first: a player throws in a garage with no signal, and sessions sync later, sometimes twice, sometimes out of order — so idempotency is a requirement on every write endpoint, not a nicety. Everything a player sees is in their own timezone, so day boundaries cannot be computed in UTC and cannot be trusted from the client either. Training reminders need minute-level accuracy, which on Vercel means a cron that runs every minute and finishes inside its budget. And the hardest one: training plans are editable, but streaks are historical — changing a plan today must not rewrite whether you kept your streak last Tuesday.

This is a Next.js App Router API on Vercel with Neon Postgres over Drizzle, deployed through a debug → dev → staging → main branch flow with a separate database per environment. It is deliberately one deployment rather than a service split: the difficulty here is data modelling and query correctness, not throughput, and splitting would have added network boundaries between things that need to be consistent with each other. Routes are kept thin — authenticate, validate with zod, shape errors — and the work lives in lib/, grouped by domain (statistics, streaks, notifications, auth, recommendations). Rate limiting sits in lib/utils/rate-limit.ts on Upstash Redis with an in-memory fallback for local dev, because Vercel functions do not share process memory and a per-instance counter would not have limited anything.

Two decisions shape most of the code. First, aggregation stays in SQL. A year view is thousands of throws, and bucketing plus averaging them in Postgres — with AT TIME ZONE applied inside the query so the day boundaries are the player's — keeps the endpoint fast on a cold function; the controller only fills gaps, so a week with no darts still returns seven labelled points with null values and the client never reasons about missing days. The cost is long SQL that was duplicated per period and per game mode, which I paid down by extracting shared fragments into constants rather than by moving the work into TypeScript. Second, training plan items are versioned rather than mutated: valid_from and deactivated_at on training_plan_items, deactivated_at on training_plans. Editing a plan retires the old row and writes a new one, so "was this a planned training day?" stays answerable for any past date. Hard updates would have been far simpler and would have silently corrupted every historical streak.

I started this expecting a CRUD backend — record matches, return them — and assumed statistics would be the easy part. Statistics and streaks between them account for most of the rework in the repo.

The first real mistake was writing the stats SQL inline in route files. It worked, so I did it again in a second route, and the two copies drifted almost immediately: one read the three-dart average from one JSON path and the other from a different one, so the dashboard and the statistics screen disagreed for a while before anyone noticed. Pulling it into lib/statistics and splitting queries from calculations from pure helpers was the change that made the module maintainable, and I should have done it at the second copy rather than the tenth.

Streaks were worse, and the git history does not hide it — there is a commit literally called streak revert, another called fix all identified 14 issues, and a run of narrowly-scoped fixes after each of those. Every time I fixed the streak calculation, the next plan-editing feature broke it again. The moment it clicked was realising I was not fixing a streak bug at all: I was repeatedly discovering that a mutable training plan cannot answer questions about the past. Once plans and plan items carried their own validity windows, most of that class of bug stopped being possible.

The most recent one taught me a different lesson. A user reported that win rate versus human never appeared for one game mode, and my instinct was that the aggregation was wrong. It was not — the classification feeding it was, and it had been wrong for every game mode. It only got reported for one because that mode's human matches happened to arrive through the other table.

What I would do differently: normalise the two session tables at the write layer on day one, even at the cost of an awkward early migration. Every read query in this repo pays a tax for that split, and the tax grows with each new game mode.

Shipped and running in production across three environments (dev, staging, production), each with its own Neon database, deployed from a debug → dev → staging → main branch flow.

Provable from the repo: 65 API route handlers across 17 groups; 26 tables and 34 migrations; four game modes recorded, three of them surfaced in statistics (X01, Around the Clock, Bob's 27) across nine variants; rate limiting at 1000 requests per hour per client with a 5-per-hour limit on OTP; a notifications cron running every minute with a 300-second function budget; a GitHub Actions job backing up all three databases to Vercel Blob every Sunday at 02:00 UTC; 351 commits between July 2025 and July 2026.

Ten TODO markers remain, all of them the same unfinished thread: subscription status is hardcoded at the auth endpoints pending the RevenueCat integration.

Clutch Dart is an international dart training and game tracking application based in Germany. The backend powers a full-featured mobile app experience — handling real-time game sessions, personalized training plans, player statistics, and a subscription-based ecosystem.

Built with Next.js App Router and TypeScript, using PostgreSQL on Neon with Drizzle ORM. The system includes JWT dual-token authentication with Google/Apple OAuth, a full X01 game engine, weekly training plans with timezone-aware scheduling, and RevenueCat-integrated subscriptions.