FlowRoll

A BJJ training log. Log what you rolled, watch your mat time and submissions trend, get feedback from an AI coach, follow training partners and see what they're doing.

Built for one user first, but multi-user from day one.

Stack

• Next.js 14 (App Router) + TypeScript
• Supabase — Postgres + magic-link & Google auth + Row-Level Security + Storage (the avatars bucket for profile photos)
• @supabase/ssr for browser / server / middleware clients
• Recharts for the dashboard charts
• Anthropic SDK (Claude) for the Coach chatbot and weekly recaps
• react-markdown for rendering Coach replies
• Tailwind with a custom belt-color theme
• Vitest for unit tests (npm test) — see lib/stats.test.ts
• Deployed on Vercel

Local setup

npm install
cp .env.local.example .env.local   # then fill in your Supabase URL + anon key
npm run dev

Then open http://localhost:3000.

Required env vars

NEXT_PUBLIC_SUPABASE_URL=https://<project>.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=<your publishable / anon key>
NEXT_PUBLIC_SITE_URL=http://localhost:3000   # used by magic-link + WHOOP redirects
ANTHROPIC_API_KEY=sk-ant-...                 # server-only — powers the Coach chatbot
# Optional integrations (each feature no-ops when its vars are unset):
WHOOP_CLIENT_ID=...                          # WHOOP OAuth app (developer-dashboard.whoop.com)
WHOOP_CLIENT_SECRET=...                      # also verifies webhook signatures
NEXT_PUBLIC_SENTRY_DSN=...                   # error monitoring
YOUTUBE_API_KEY=...                          # YouTube Data API v3 — study video shelves + Coach find_videos

WHOOP integration

Create an app at developer-dashboard.whoop.com with scopes read:recovery read:cycles read:workout read:sleep read:profile offline, set the redirect URL to https://<your-domain>/api/whoop/callback, and (optionally) the webhook URL to /api/whoop/webhook. Put the client id/secret in the env vars above. Users then hit Connect WHOOP in Settings. What it powers: strain/HR/calories on your own session cards; a recovery-vs-feel and strain-vs-mat-time chart on the dashboard; a Coach get_whoop_data tool ("should I train today?"); auto-draft nudges when WHOOP logs a jiu-jitsu workout you haven't; and recovery context in the weekly recap. Health data is owner-only — followers never see it.

(Gym autocomplete uses a free OpenStreetMap geocoder — no key required.)

Public REST API

Docs live at /developers. Users mint bearer keys (frk_…, shown once, sha256-stored) in Settings → Developer, optionally with write scope. Endpoints under /api/v1: me, sessions (GET list / GET by id / POST), stats. Auth, scopes, and a 1,000 req/day quota are enforced inside SECURITY DEFINER RPCs (api_authenticate + api_get_*/api_create_session), so every query is scoped to the key's owner — the route handlers only ever hold the anon client. CORS is open (*) since keys are the credential.

YouTube study suggestions

Set YOUTUBE_API_KEY (Google Cloud → enable YouTube Data API v3 → create an API key — the default free quota needs no billing account). The dashboard then grows a Study section: escape videos for the submission that catches you most, detail videos for your best weapon. Coach also gains a find_videos tool. Searches are cached in study_cache for 7 days (shared across users) to stay far under the 100-searches/day free quota.

Supabase setup

1. Create a new Supabase project.
2. Open the SQL editor and run supabase_schema.sql — it's idempotent, you can re-run it.
3. Authentication → Providers → enable Email (magic link) and Google.
4. Authentication → URL Configuration → add your dev URL (and later your Vercel URL) to "Site URL" and "Redirect URLs".

This is the beginning of the README. Read the rest at the original. Read the full README ↗