SSI Scoreboard

Live stage-by-stage comparison tool for IPSC competitions on shootnscoreit.com.

The official site only lets you view one competitor at a time. This app lets you select any group of competitors and compare their results across every stage side-by-side -- including during an active match before official results are published.

Live instance: scoreboard.urdr.dev -- not affiliated with or endorsed by ShootNScoreIt.

Prerequisites

• Node.js 20+
• pnpm 10+ (corepack enable && corepack prepare [email protected] --activate)
• A ShootNScoreIt API key (account settings on shootnscoreit.com)

Local Setup

pnpm install
cp .env.local.example .env.local   # then fill in SSI_API_KEY
pnpm dev                            # http://localhost:3000

Deployment

The app supports two production targets, selected at build time via DEPLOY_TARGET. Both require a Redis instance for hot caching, and a relational store (SQLite or D1) for persistent shooter / match metadata that survives Redis flushes.

Docker / Docker Compose

cp .env.local.example .env.local   # fill in SSI_API_KEY, CACHE_PURGE_SECRET
pnpm docker:build                   # builds image
pnpm docker:up                      # starts redis + app on port 3000

REDIS_URL is set automatically via the compose service name. Two named volumes persist state across container restarts:

• redis_data -- Redis hot cache
• shooter_data -> /app/data -- SQLite store (shooter profiles, match indices, achievements, historical match cache)

Without Docker Compose (bare server, Kubernetes, Fly.io): run a Redis instance and set REDIS_URL to its connection string (rediss:// for TLS). Mount a writable volume at ./data/ (or set SHOOTER_DB_PATH) so the SQLite database persists. The app uses lazyConnect: true, so a missing Redis at startup is non-fatal -- requests fall back to direct GraphQL fetches.

Cloudflare Pages

The Cloudflare build swaps in HTTP-based adapters at build time:

• @upstash/redis instead of ioredis (Workers cannot open TCP)
• Cloudflare D1 instead of better-sqlite3 (Workers have no persistent disk)

You will need an Upstash Redis database and a D1 database.

pnpm cf:build    # DEPLOY_TARGET=cloudflare + @opennextjs/cloudflare build
pnpm cf:deploy   # build + wrangler deploy

Full step-by-step walkthrough -- wrangler login, secrets, custom subdomain, verification, troubleshooting -- in docs/deploy-cloudflare.md.

Note on serverless platforms without persistent disk (Vercel, Netlify default): the app's SQLite AppDatabase needs writable disk for shooter/match metadata. These platforms only work if you switch the persistence layer to D1 or a managed SQL store -- they are not currently supported targets.

Environment Variables

The most common ones an operator needs:

Variable	Target	Description
SSI_API_KEY	Both	ShootNScoreIt API key -- server-side only, never exposed to browser
CACHE_PURGE_SECRET	Both	Secret for the admin cache-purge endpoint -- any strong random string
NEXT_PUBLIC_BUILD_ID	Both	Git SHA baked into the bundle for version detection (auto-injected by pnpm docker:build)
REDIS_URL	Docker	Redis connection string (redis://localhost:6379, or rediss://... for TLS)
SHOOTER_DB_PATH	Docker	Optional. Path to SQLite database file. Defaults to ./data/shooter-index.db
UPSTASH_REDIS_REST_URL	Cloudflare	REST URL from the Upstash console
UPSTASH_REDIS_REST_TOKEN	Cloudflare	REST token from the Upstash console
MCP_SECRET	Both	Optional. If set, POST /api/mcp requires Authorization: Bearer <MCP_SECRET>
NEXT_PUBLIC_APP_URL	Both	Base URL for MCP tool internal API calls. Required on Cloudflare Pages
AI_PROVIDER / AI_MODEL / AI_API_KEY / AI_API_URL	Both	AI coaching tips. Set to "openai" or "cloudflare"; omit AI_PROVIDER to disable

Full reference -- including TTL tunables, telemetry sampling, probe kill switches, and all internal flags -- in docs/env-vars.md.

Usage

1. Browse competitions month by month using the month navigator on the landing page, or paste a match URL (https://shootnscoreit.com/event/22/26547/) to jump straight to a match. The collapsible Filters panel narrows results by discipline, country, and level.
2. Select competitors individually by name, number, or club -- or tap Add squad to load an entire IPSC squad at once (up to 12 competitors total).
3. Multiple analysis views update immediately (stage table, hit-factor and HF% charts, speed/accuracy scatter, balance radar, coaching panels, style fingerprint, AI tip).
4. Use the Share button to copy the link with selections encoded -- recipients open the same match with the same competitors pre-selected.

Features

Comparison & rankings

• Side-by-side stage table with hit factor, time, hit zones, rank, percentile, shooting order, stage difficulty, run classification
• Group / Division / Overall ranking contexts
• Delta heatmap view (each cell relative to the group leader)
• Incomplete scorecard flag (IPSC rule 9.7.6.2)
• DQ banner and clean-match indicator

Charts

• Hit-factor bar chart with optional benchmark overlay
• HF% vs stage-winner line chart
• Speed-vs-accuracy scatter with iso-HF reference lines
• Stage-balance polar radar
• Style fingerprint (alpha ratio vs PPS) with archetype labels
• Style radar (composure, consistency, multi-axis profile)
• Info popovers on every chart explaining axes and reading tips

Coaching analysis

• Consistency score (CV of HF% across fired stages), efficiency (points per shot)
• Penalty rate, match-percentage impact, points left on the table
• "One stage away" what-if analysis
• AI coaching tips for completed matches (sparkle icon; requires AI provider configuration)

Cross-competition (shooter dashboard)

• Per-shooter career view with match history, aggregate stats
• Tiered achievements that survive the 200-match prune window
• Manual match URL submission, dashboard backfill from cached data

Search & navigation

• Month-by-month browser; typing a query switches to full-history search mode
• Filters: firearms, country (ISO 3166-1 alpha-3, defaults to SWE), level (L2+, L3+, L4+, all)
• Recent matches list (localStorage)
• Shareable URLs encode the full competitor selection

Platform

• Server-side cache with smart TTL tiers (future / pre-match / active / complete)
• Persistent SQLite/D1 store for shooter profiles, match indices, achievements, historical match cache
• Dynamic Open Graph images per match (Satori / next/og)
• MCP server (HTTP + stdio transports) -- 7 tools for AI assistant integration
• New-version banner; PWA installable; mobile-first (390px); WCAG 2.1 AA; dark mode

Development Commands

pnpm dev          # start dev server on port 3000
pnpm build        # production build
pnpm lint         # ESLint -- zero warnings required
pnpm typecheck    # TypeScript type check -- zero errors required
pnpm test         # Vitest unit + component tests
pnpm test:watch   # Vitest in watch mode
pnpm test:e2e     # Playwright E2E tests (mocked API, no live key needed)
pnpm test:e2e:ui  # Playwright with interactive UI

Quality bar: pnpm lint, pnpm typecheck, and pnpm test must all pass with zero errors and zero warnings before merging. CI enforces this.

Intentionally pinned major versions

Held back from latest -- don't upgrade without a migration plan:

Package	Pinned at	Why
zod	3.x	Zod 4 has breaking API changes. Needs a dedicated migration across lib/ and app/api/.
eslint	^9	ESLint 10 is brand-new; wait until eslint-config-next officially supports it as a peer dep.

MCP Server

SSI Scoreboard exposes an MCP server so Claude and other AI assistants can query competition data directly. Seven tools: search_events, get_match, compare_competitors, get_stage_times, get_popular_matches, get_shooter_dashboard, find_shooter.

HTTP transport (public, no local setup needed):

POST https://scoreboard.urdr.dev/api/mcp

stdio transport (local subprocess) -- .mcp.json at repo root pre-registers two stdio servers:

• ssi-scoreboard -- calls the live production instance (no local server needed)
• ssi-scoreboard-local -- calls localhost:3000 (requires pnpm dev running)

Claude Code picks up .mcp.json automatically when you open the repo.

For client-specific setup (Claude Desktop, generic HTTP clients), example prompts, and troubleshooting, see docs/mcp.md.

Architecture

Browser -> Next.js Route Handlers -> shootnscoreit.com/graphql/
         ^
    POST /api/mcp (MCP clients / Claude)

The SSI_API_KEY lives server-side only and is never sent to the browser. Route Handlers are the only place that touches the upstream GraphQL API.

More diagrams (the live scorecard refresh cycle and the tiered match data store) are in docs/diagrams/, rendered inline there; the .html files in that directory are interactive versions of the same diagrams.

Two persistence layers:

• Redis (ioredis on Docker, @upstash/redis on Cloudflare) -- hot cache for active matches and per-request data.
• AppDatabase (SQLite on Docker, D1 on Cloudflare) -- durable store for shooter profiles, match indices, achievements, and historical match data offloaded from Redis.

Key entry-points:

• app/api/match/[ct]/[id]/ -- match metadata (stages, competitors, scoring progress)
• app/api/compare/ -- fans out scorecard queries, merges ranking data
• app/api/events/ -- event search with date-range, firearms, country, level filters
• app/api/shooter/[shooterId]/ -- cross-competition shooter dashboard
• app/api/og/match/[ct]/[id]/ -- dynamic Open Graph images
• app/api/mcp/ -- MCP HTTP endpoint (JSON-RPC, single-shot transport)
• app/api/coaching/ -- AI coaching tips
• app/api/admin/cache/ -- authenticated cache purge / health / force-refresh

For the full module layout and contributor conventions, see CLAUDE.md.

Design System

This project uses Tailwind v4 with CSS custom property design tokens (OKLCH color space) defined in app/globals.css. Always use semantic token classes (bg-background, text-muted-foreground, etc.) rather than raw palette classes (bg-gray-100). Dark mode is supported via next-themes and the .dark class -- all tokens have light and dark values. A theme toggle in the toolbar lets users switch at runtime.

shadcn/ui is the primary component library. Never modify files in components/ui/ directly; use pnpm dlx shadcn@latest add to update them.

Accessibility

This project targets WCAG 2.1 AA compliance:

• All interactive elements are keyboard-navigable with a visible focus ring
• Minimum touch target size 44x44px (enforced globally in globals.css)
• Error states use role="alert" for screen reader announcements
• Color is never the only means of conveying information -- pairs with shape, icon, or pattern
• Semantic HTML throughout (<button>, <table>, <th scope>, etc.)

Support

If this tool saves you time at the range, consider buying me a coffee: