Grand Football

An invite-only Premier League prediction game for a private group of ~30 players. Participants predict exact scorelines for each gameweek's fixtures and earn points based on accuracy — building toward a season-long leaderboard competition.

• Features
• Tech Stack
• Project Structure
• Scoring System
• Getting Started
• Environment Variables
• Database
• Authentication
• Admin Panel
• API Routes
• Testing
• Scripts
• Deployment
• Troubleshooting

• Score Predictions — Submit exact home/away scoreline predictions for every fixture before the deadline
• Dynamic Leaderboard — Season-long and monthly leaderboards ranked by points, with tie-breaking rules
• Live Match Updates — Real-time scoring during active gameweeks with live standings
• Star Games — Designated high-value fixtures where an exact score is worth 10 pts (double)
• Monthly Bonus — +10 pts for players who submit all predictions on time every fixture in the calendar month
• Badges & Milestones — Earned for achievements (e.g. perfect gameweek, consecutive bonuses)
• Late Submission Penalties — Points deducted if predictions are submitted after the gameweek deadline
• Prediction Leakage Prevention — Other users' predictions are hidden until a player has submitted their own (or kickoff passes)
• Admin Tooling — Full fixture/season management, leaderboard editing with audit trail, score overrides

src/
├── app/
│   ├── (authenticated)/          # All player-facing pages (require login)
│   │   ├── page.tsx              # Dashboard — stats, upcoming fixtures, bonus tracker
│   │   ├── leaderboard/          # Season & monthly leaderboard
│   │   ├── fixtures/             # Gameweek fixture list with prediction form
│   │   ├── match/[id]/           # Individual match detail & predictions view
│   │   ├── profile/[id]/         # Player profile & prediction history
│   │   ├── rules/                # Scoring rules explanation page
│   │   ├── settings/             # User account settings
│   │   └── admin/                # Admin-only management pages (see Admin Panel)
│   ├── api/
│   │   ├── predictions/          # CRUD for prediction submissions
│   │   ├── live-fixtures/        # Polling endpoint for live match scores
│   │   └── cron/
│   │       ├── sync-fixtures/    # Syncs fixture data from external football API
│   │       ├── calculate-scores/ # Scores all predictions for finished fixtures
│   │       └── monthly-bonus/    # Awards monthly bonus points (runs on 1st of month)
│   ├── auth/                     # Supabase Auth callback handlers
│   └── login/                   # Magic link + Google OAuth login page
├── components/                   # Shared UI components
│   ├── bonus-tracker.tsx         # Monthly bonus progress bar
│   ├── countdown.tsx             # Live countdown to deadline/kickoff
│   ├── fixture-card.tsx          # Fixture card with score & prediction display
│   ├── leaderboard-table.tsx     # Full leaderboard table
│   ├── live-leaderboard.tsx      # Live provisional leaderboard during gameweek
│   ├── prediction-form.tsx       # Score input form with deadline enforcement
│   └── podium.tsx                # Top-3 podium display
├── hooks/
│   └── use-provisional-scoring.ts  # Client-side live score + penalty calculation
├── lib/
│   ├── scoring/
│   │   ├── engine.ts             # Core points calculation (mirrors DB function)
│   │   ├── late-penalty.ts       # Late submission penalty tiers
│   │   ├── explanations.ts       # Human-readable reason code labels
│   │   └── types.ts              # Scoring type definitions
│   ├── constants.ts              # All point values and thresholds
│   ├── database.types.ts         # Auto-generated Supabase TypeScript types
│   └── utils.ts                  # Shared utilities (outcome calculation, formatting)
├── middleware.ts                  # Auth guard — redirects unauthenticated users
supabase/
└── migrations/                   # Ordered SQL migrations (00001 → 00021)
docs/
├── architecture/                 # Technical specs, DB schema, API contracts
└── strategy/                     # User stories, UX specs, design decisions
scripts/                          # One-off data migration & seeding scripts

Points are awarded per fixture using a 4-tier priority chain (first match wins):

+10 pts if every prediction in the calendar month was submitted before the gameweek deadline (admin-set, or the earliest kickoff as a fallback). A single late or missing prediction forfeits the entire month's bonus.

Applied once per gameweek based on how late the user's latest prediction was:

1. Total points ↓
2. Exact score count ↓
3. Correct outcome count ↓
4. Zero-point matches ↑ (fewest)

• Node.js 18+
• A Supabase project
• Supabase CLI

npm install
npm run dev

App runs at http://localhost:3000.

npx supabase db push

Create a .env.local file in the project root:

NEXT_PUBLIC_SUPABASE_URL=https://<your-project>.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=<your-anon-key>
NEXT_PUBLIC_SITE_URL=http://localhost:3000
SUPABASE_SERVICE_ROLE_KEY=<your-service-role-key>
CRON_SECRET=<a-random-secret-for-cron-route-auth>

CRON_SECRET is used to authenticate calls to /api/cron/* routes. Set the same value in your Vercel environment and in the Supabase pg_cron job configuration.

Powered by Supabase (PostgreSQL) with Row Level Security (RLS) on every table.

• Magic link — passwordless email OTP (10-minute expiry)
• Google OAuth — PKCE flow via Supabase Auth
• Allowlist gating — only emails in the allowlist table can sign up or log in
• Sessions — 30-day persistent sessions managed by Supabase
• Route protection — src/middleware.ts redirects unauthenticated users to /login

Accessible at /admin/* for users with profiles.is_admin = true.

All /api/cron/* routes require Authorization: Bearer <CRON_SECRET>.

Tests use Vitest and are focused on the deterministic scoring engine.

npm test            # run all tests
npm run test:watch  # watch mode
npm run coverage    # generate coverage report (100% threshold on scoring module)

Test files live alongside the source they cover in src/lib/scoring/.

Utility scripts in /scripts for one-off data operations. Run with Node:

node scripts/<script-name>.mjs

Deployed on Vercel. The vercel.json wires up the three cron jobs:

Set all environment variables in the Vercel dashboard under Settings → Environment Variables.

Next.js dev error: Cannot find module './276.js'

Multiple next dev processes running simultaneously can corrupt the .next cache. Fix:

pkill -f "next dev" 2>/dev/null || true
pkill -f "node.*next/dist/bin/next" 2>/dev/null || true
rm -rf .next
npm run dev

Avoid running parallel dev servers. npm run dev is pinned to port 3000.