Kicksmash — padel match-up in one link

Mobile-first web app for organizing padel matches with zero app installs, zero accounts, zero passwords. Create a match, share kicksma.sh/{code} on WhatsApp or Telegram, friends tap → enter a name once → they're in.

• Stack: Next.js 15 (App Router, TypeScript) · Supabase Postgres + Drizzle · Resend · next-intl (EN/RU/ES) · Tailwind v4 · Vercel (Cron + OG images).
• Open source under the Apache License 2.0. Run your own copy, build on it, send a PR: see CONTRIBUTING.md and SECURITY.md.
• Identity: one-time name entry → player UUID in a signed httpOnly cookie (1 year) + localStorage mirror. Cross-device: every player has a private personal link (/p/{token}, shown on My matches, in every email and in the calendar invite) that signs any device in; an email that was used before can restore history with a 6-digit code, merging all identities that share it. The home-screen shortcut opens the personal link, and calendar entries and emails carry the private event link (/p/{token}/{code}: signs the device in, opens the match). A newly added email receives the personal link (inside the calendar invite when in a match, otherwise on its own). Tokens are 12 characters; older 32-char tokens keep working as previous_token after the lazy shortening. An email can be changed but never blanked once set; the previous address is kept as recovery_email, so a restore code sent to either address gets the player back in. "Email me this link" on My matches mails the personal link (native share, copy and QR are the other options).
• Push reminders: Web Push (VAPID) one hour before each match, for every device the player enabled it on (iPhone: from the home-screen app). /api/cron/push is called every 5 minutes by Supabase pg_cron + pg_net (Vercel Hobby cron is daily). Set VAPID_PUBLIC_KEY, VAPID_PRIVATE_KEY, VAPID_SUBJECT.
• Links: /{code} (4 chars, public) · /{code}/i/{6} (personal invite) · /{code}/manage/{10} (organizer secret).
• Agent-native and open. A public REST API (OpenAPI 3.1 at /api/openapi.json), an MCP server at /mcp that any assistant adds by URL, instant self-serve keys, signed webhooks, llms.txt, /.well-known/mcp.json, a robots.txt that welcomes AI crawlers, AGENTS.md, an installable skill (npx skills add evhg/padel-matchup), calendar feeds per group and venue. Public data is CC BY 4.0. See /developers and /agents.
• Email is optional everywhere. Without RESEND_API_KEY the app runs fully with email features hidden.
• Privacy, short and cheeky: /about (one faint footer link) says what is stored, what is never done, and how to leave. Every organizer-initiated email (invites, invite reminders) carries a signed one-tap /unsubscribe link; a player adding their own address again lifts the opt-out. "Delete my account" at the bottom of My matches wipes personal data, releases upcoming spots and cancels the player's own upcoming matches; old scores stay as "Deleted player".
• Levels: every player can declare a padel level (0–7 in quarter steps, the scale the padel apps use) once, from My matches or the first time a ranged match asks for it. It shows as a small chip next to the name everywhere (roster, standings, team picker). Results nudge it: when the organizer confirms a 2v2 score or finalizes a tournament, a small Elo-style delta (at most ±0.10 per match, ±0.12 per tournament) is applied once per event and logged ("3.25 → 3.30 after a match"). Players without a level neither move nor count. Organizers can set a level range per match or tournament: presets Bronze 1.0–2.5, Silver 2.5–3.5, Gold 3.0–4.5, Platinum 4.5+, or a custom min–max. Players inside join as usual; players outside ask to join and the organizer approves (seats them, or waitlists them when full) or declines, with the answer shown in the join bar and the activity feed. Reserved/invited players and the organizer bypass the range. The score panel suggests balanced teams (smallest level gap) when all four have levels. My matches gets a stats strip: played, won, win rate, podiums.
• Abuse limits (per UTC day unless noted, generous for humans, tight for scripts): 40 new identities per IP, 20 matches per player, 40 invitations per organizer, 30 joins per player per hour, 10 email changes, 5 personal-link mails, 20 restore codes per IP, 60 browser crash reports per IP. Counters live in metrics_daily, no extra infrastructure. Hitting one returns "too many" and nothing else happens.

---

Quick start (zero config, ~2 min)

pnpm install
pnpm dev

That's it. With no DATABASE_URL the app boots an embedded PGlite database in ./.pglite, applies migrations and seeds two example events:

URL	What you get
http://localhost:3000/PLAY	Upcoming match: 2 joined, 1 reserved invite, 1 open spot
http://localhost:3000/PAST	Finished match with an organizer-confirmed 3-set score
http://localhost:3000/new	Create your own

Copy .env.example to .env to change anything. All flows (join, waitlist, invites, scores, "My matches", OG previews) work end-to-end without any keys.

pnpm test        # vitest: slot-claim concurrency, invite transitions, score-lock rules, reminders, identity, americano rotation, rate limits, opt-outs, account deletion
pnpm typecheck
pnpm lint
pnpm build
pnpm e2e         # Playwright journeys (core, americano, levels, viral, groups, venues, agents, formats) against a fresh production build; first time: pnpm exec playwright install chromium

pnpm e2e boots next start on port 3001 with a throwaway PGlite database, a dummy Resend key (email UIs on, sends fail harmlessly) and generated VAPID keys, then runs every e2e/*.mjs suite. SHOTS=./shots keeps full-page screenshots; PW_CHROMIUM=/path/to/chromium uses a preinstalled browser. GitHub Actions runs typecheck, lint, vitest on PGlite and on a real Postgres service, the build, and the e2e suites on every push and pull request (.github/workflows/ci.yml).

Tests run on in-memory PGlite by default. To run them against a real Postgres (true concurrency), point TEST_DATABASE_URL at a disposable database — its public schema is dropped before each test file:

TEST_DATABASE_URL=postgres://postgres:postgres@localhost:5432/padel_test pnpm test

---

Environment variables

Only one variable is required in production: the database URL. Everything else has a safe default.

Variable	Required	Purpose
DATABASE_URL	✅	Supabase Transaction pooler string (port 6543), exactly as Supabase's Connect dialog shows it. POSTGRES_URL (Vercel ⇄ Supabase integration) works too. Empty → embedded PGlite (local dev only).
DATABASE_PASSWORD	if the URL still says [YOUR-PASSWORD]	The app substitutes and percent-encodes it for you.
APP_BASE_URL	no	Defaults to the Vercel production domain. Set it locally or on other hosts.
SESSION_SECRET	recommended	Signs the identity cookie. Without it a stable secret is derived from the database URL.
CRON_SECRET	recommended	Protects /api/cron/hourly and /api/cron/push. Vercel sends it automatically when set.
DIRECT_DATABASE_URL	no	Direct (5432) URL for pnpm db:migrate. Not needed: the app migrates itself on first connection (AUTO_MIGRATE=false disables).
RESEND_API_KEY	no	Enables all email (calendar invites, notifications, reminders).
VAPID_PUBLIC_KEY / VAPID_PRIVATE_KEY / VAPID_SUBJECT	no	Enables push reminders (npx web-push generate-vapid-keys).
TELEGRAM_BOT_TOKEN / TELEGRAM_WEBHOOK_SECRET / TELEGRAM_BOT_USERNAME	no	Enables the Telegram bot and Telegram sign-in. Register the webhook once with GET /api/telegram/setup (Bearer CRON_SECRET).
ANTHROPIC_API_KEY	no	Drafts replies for the listening desk (use a key with a monthly spend cap). LISTEN_MODEL overrides the model.
TELEGRAM_OWNER_ID	no	The owner's Telegram id: drafts are sent there for one-tap approval and /admin/listen opens for that account only.
PASSPORT_PRIVATE_KEY / PASSPORT_PUBLIC_KEY	no	Ed25519 key pair (raw 32-byte hex each) that signs player passports. Without them passports carry alg: "none". Generate with node -e "const {generateKeyPairSync}=require('crypto');const k=generateKeyPairSync('ed25519');console.log(k.publicKey.export({type:'spki',format:'der'}).subarray(-32).toString('hex'), k.privateKey.export({type:'pkcs8',format:'der'}).subarray(-32).toString('hex'))".
DISCORD_BOT_TOKEN / DISCORD_PUBLIC_KEY	no	Enables the Discord bot (slash commands, cards, the in-server helper). Register commands and the interactions URL once with GET /api/discord/setup (Bearer CRON_SECRET); it returns the install link. DISCORD_INVITE_URL shows the server on the community pages.
REDDIT_CLIENT_ID / REDDIT_CLIENT_SECRET / REDDIT_USERNAME / REDDIT_PASSWORD	no	Lets an approved reply be posted on Reddit as the project's account. Without them, Approve means copy and paste.
EMAIL_FROM	no	Defaults to Kicksmash <matches@<your domain>>; the domain must be verified in Resend.

Generate secrets: openssl rand -base64 32. Check a deployment any time at /api/health (no secrets returned).

---

Production setup

Two ways. Option A needs no terminal at all. Option B scripts everything that can be scripted.

Option A — browser only (≈ 20 min + DNS)

1. Supabase (5 min): https://supabase.com/dashboard/new → create a project, save the database password. Click Connect → copy the Transaction pooler string (port 6543). Leave [YOUR-PASSWORD] in it.
2. Vercel (5 min): https://vercel.com/new → Import evhg/padel-matchup (the code must be on the repo's default branch). Under Environment Variables add:
   • DATABASE_URL = the string from step 1, unchanged
   • DATABASE_PASSWORD = your database password Click Deploy. The first request creates the tables automatically.
3. Check: open https://<your-project>.vercel.app/api/health → "database":"connected".
4. Domain (5 min + waiting): Vercel → Project → Settings → Domains → Add kicksma.sh (and www.kicksma.sh). Vercel shows the records. At Porkbun → Domain Management → kicksma.sh → DNS: delete the parking ALIAS/CNAME records, then add the A record (Host empty) and the www CNAME with the values Vercel shows. Wait until Vercel says Valid Configuration.
5. Later, optionally: SESSION_SECRET, CRON_SECRET, RESEND_API_KEY + EMAIL_FROM in Settings → Environment Variables, then Deployments → ⋯ → Redeploy.

Cron runs daily at 07:00 UTC out of the box, which is what Vercel's Hobby plan allows. On Pro, change the schedule in vercel.json to 0 * * * * for hourly reminders.

Option B — CLI

1. Supabase (≈ 10 min)

1. Create a project at https://supabase.com/dashboard/new (or npx supabase projects create kicksmash --org-id <id> --db-password <pw> --region eu-central-1). Pick the region closest to your players. Save the DB password.
2. Project → Connect (top bar) → copy two URLs:
   • Transaction pooler (...pooler.supabase.com:6543/postgres) → DATABASE_URL
   • Direct connection (db.<ref>.supabase.co:5432/postgres) → DIRECT_DATABASE_URL Append ?sslmode=require to both if it isn't there.
3. Put them in .env. The schema is applied automatically on first connection; to do it explicitly:

   pnpm db:migrate     # runs ./drizzle/*.sql against DIRECT_DATABASE_URL
   pnpm db:seed        # optional: example matches PLAY + PAST
   

4. Sanity check: pnpm dev now says nothing about PGlite and /api/health reports "database":"connected".

No Supabase Auth, RLS or storage is used — only Postgres.

2. Resend (≈ 15 min incl. DNS)

Skip this entirely if you don't want email yet; deploy never blocks on it.

1. https://resend.com → API Keys → create key (Sending access) → RESEND_API_KEY.

2. Domains → Add domain → kicksma.sh (region: same continent as Vercel). Resend shows 3–4 DNS records.

3. Add them at Porkbun (see §4 for the editor quirks). Names below are what Porkbun expects in the Host field (it appends .kicksma.sh itself) — copy the exact values from Resend's screen:

   Type	Host	Value
   TXT	resend._domainkey	p=MIGf… (DKIM, from Resend)
   MX	send	feedback-smtp.<region>.amazonses.com, priority 10
   TXT	send	v=spf1 include:amazonses.com ~all
   TXT	_dmarc	v=DMARC1; p=none;

4. Back in Resend click Verify. Usually green within minutes (up to an hour).

5. Set EMAIL_FROM="Kicksmash <matches@kicksma.sh>".

Emails sent: calendar invite (.ics, METHOD:REQUEST, stable UID) on join/confirm/promotion · updated/cancelled .ics · organizer notices (joined / left / confirmed / declined / promoted) · 24h invitee reminders · one post-match score reminder · welcome mail with the personal link · restore codes. All EN + RU + ES by recipient language. Invites and invite reminders skip addresses on the opt-out list and carry the unsubscribe link; the activity notices respect the player's "email me" switch.

3. Deploy to Vercel via CLI (≈ 10 min)

pnpm dlx vercel@latest login          # opens the browser; or: vercel login --github
pnpm dlx vercel link                  # create a new project "kicksmash" (framework auto-detected: Next.js)

# Production env vars (paste values when prompted; repeat for each)
for v in DATABASE_URL DIRECT_DATABASE_URL SESSION_SECRET CRON_SECRET APP_BASE_URL RESEND_API_KEY EMAIL_FROM; do
  pnpm dlx vercel env add $v production
done
# APP_BASE_URL = https://kicksma.sh

pnpm dlx vercel --prod                # first production deploy

Token flow for CI / headless machines: create a token at https://vercel.com/account/tokens and use vercel --token $VERCEL_TOKEN --prod --yes.

Build settings need no changes (pnpm build, Node 20+). The migration is not run at build time — run pnpm db:migrate locally whenever drizzle/ changes.

4. Custom domain kicksma.sh at Porkbun (≈ 10 min + DNS propagation)

Production goes straight to the custom domain; no *.vercel.app staging step.

1. Add the domain to the project:

   pnpm dlx vercel domains add kicksma.sh
   pnpm dlx vercel domains add www.kicksma.sh   # optional; Vercel redirects www → apex
   

   The CLI (and Project → Settings → Domains) prints the exact records to create.

2. Porkbun → Domain Management → kicksma.sh → DNS.

   • Delete Porkbun's default records first (the parking ALIAS/CNAME on @ and www). Vercel's A record can't coexist with an ALIAS on the apex.
   • The Host field is relative: leave it blank for the apex, type www for www.

3. Create — copy the exact values from Vercel's domain screen (typical values shown):

   Type	Host	Answer
   A	(blank)	76.76.21.21
   CNAME	www	cname.vercel-dns.com

4. Wait for Vercel to show Valid Configuration (vercel domains inspect kicksma.sh). SSL is issued automatically. Porkbun's TTL is 600s; worst case a couple of hours.

5. Redeploy once so APP_BASE_URL links are baked correctly: pnpm dlx vercel --prod.

6. Test the link preview: paste https://kicksma.sh/PLAY into a WhatsApp/Telegram chat — title, date/time, venue and "2/4 players — tap to join" should render. Debug with https://www.opengraph.xyz/ or curl -I https://kicksma.sh/PLAY/opengraph-image.

Also add the Resend records from §2 in the same DNS editor if you skipped them.

5. Cron (already configured, ≈ 2 min to verify)

vercel.json schedules GET /api/cron/hourly daily at 07:00 UTC (Hobby-plan safe; on Pro set 0 * * * * for hourly). Vercel automatically sends Authorization: Bearer $CRON_SECRET when that variable is set; without it the endpoint is open but every step is idempotent.

The job does: open/full → past transitions · waitlist hygiene · 24h invite reminders (email only, stops on response or start) · the single organizer score reminder (2h after start) · automatic group matches for weekly slots (with member notifications) · daily metric snapshots.

Verify: Project → Settings → Cron Jobs shows the job, or trigger by hand:

curl -H "Authorization: Bearer $CRON_SECRET" https://kicksma.sh/api/cron/hourly
# → {"ok":true,"transitionedToPast":0,"promotions":0,"inviteReminders":0,"scoreReminders":0,...}

Hobby plan crons run once a day at best-effort times; Pro runs them on the minute.

---

npm packages

The pure engines ship as packages, generated from src/lib/domain so there is one source of truth:

• @erikv69/americano: buildSchedule({ names | players, courts, rounds, seed }) for a whole americano, plus the round-by-round planners (planRound, planMexicanoRound, planKingRound), histories and standings.
• @erikv69/levels: bands, presets, ranges and levelFit, balancedTeams, matchDeltas and tournamentDeltas.

pnpm packages:build regenerates packages/*/src and packages/*/dist (both gitignored); tests/packages.test.ts builds them on every CI run. To release: bump the version in packages/<name>/package.json, build, npm publish from that directory.

Community

Questions, ideas and "I built a thing on the API" go to GitHub Discussions. Bugs go to issues. There is a Discord server too (the link is on /developers), where the bot answers questions about once an hour. The Telegram bot and the Reddit account answer people where they are; the code and the roadmap live here.

Deploy your own

Kicksmash is one Next.js project and one Postgres database, Apache-2.0. Run it for your club, your city or your country; the environment table above is the whole configuration.

Or with Docker (standalone Next.js build, about 200 MB):

docker build -t kicksmash .
docker run -p 3000:3000 --env-file .env kicksmash   # then: pnpm db:migrate against the same DATABASE_URL

Everything optional stays optional: without a Resend key no emails go out, without a bot token there is no Telegram or Discord, without an Anthropic key the listening desk only collects. Keep the /agents charter and the CC BY 4.0 notice if you keep the public API.

Product rules baked in