NFL Pick'em App

A free, friends-only NFL weekly pick'em application built with Next.js 14, TypeScript, and Vercel Postgres.

Features

• 6 Fixed Users: Victor, Mihir, Dakota, Chris, Ryan, Jihoo
• Lightweight Authentication: Name selection + shared league passcode
• Weekly Picks: Submit picks for all NFL games in a week
• Time Lock: Picks lock every Thursday 8:00 PM ET
• All-or-Nothing Scoring: Score one point per lock if every lock hits, 0 if any misses
• Automated Results & Odds: Scores and betting lines pull from ESPN without manual entry
• Pick Visibility: See others' picks only after submitting your own
• Auto Schedule: ESPN API integration for automatic game loading
• Manual Admin: Fallback for manual result entry
• Scoreboard: Season totals and weekly breakdowns
• Free Deployment: Runs entirely on free tiers

Tech Stack

• Frontend/Backend: Next.js 14 (App Router, TypeScript)
• Database: Vercel Postgres (free tier)
• ORM: Drizzle ORM
• Styling: Tailwind CSS
• Authentication: JWT with httpOnly cookies
• Time Management: Luxon
• Hosting: Vercel (free tier)
• Cron Jobs: Vercel Cron (free tier)

Quick Start

1. Clone and Install

git clone <your-repo>
cd football-locks-project
npm install

2. Environment Setup

Copy env.example to .env.local and configure:

cp env.example .env.local

Required environment variables:

• DATABASE_URL: Vercel Postgres connection string
• LEAGUE_PASSCODE: Shared passcode for league access
• JWT_SECRET: Secret key for JWT tokens
• ADMIN_PASSCODE: Admin passcode for manual results
• CRON_SECRET: Secret for cron job authentication

3. Database Setup

# Generate and run migrations
npm run db:generate
npm run db:migrate

4. Development

npm run dev

Visit http://localhost:3000 and log in with any of the 6 user names and the league passcode.

Deployment

1. Vercel Setup

1. Push code to GitHub
2. Connect repository to Vercel
3. Add Vercel Postgres database
4. Configure environment variables in Vercel dashboard

2. Database Migration

# Deploy migrations
npm run db:migrate

3. Cron Jobs

Cron jobs are declared in vercel.json and deploy automatically. Vercel runs them in UTC, and Hobby-plan jobs fire within the hour they are scheduled for (a 7:00 PM job can run as late as 7:59 PM).

Job	Expression	Eastern	Purpose
/api/cron/fetch-schedule	0 13 * * 1	Mon 9:00 AM	Refresh next week's kickoff times
/api/cron/fetch-odds	0 23 * * *	Daily 7:00 PM	Refresh lines for the current and next week
/api/cron/resolve-results	0 8 * * *	Daily 4:00 AM	Pull results and rescore the week
/api/cron/lock-reminder	0 21 * * *	Daily 5:00 PM	Nudge anyone without picks in, if kickoff is close

All three require Authorization: Bearer $CRON_SECRET, which Vercel sends automatically when CRON_SECRET is set on the project.

Vercel triggers cron jobs with a GET request, so each route exports GET. A route exporting only POST returns 405 and the job silently never runs.

Eastern times shift an hour during standard time (Nov–Mar); every job still lands well inside its window.

Odds

One ESPN scoreboard request returns moneyline, spread and total for the whole slate, so no betting API key is needed. Lines refresh once a day for the current and next week, so the board you see while picking is live.

A game's line stops updating the moment it kicks off. That freeze is the point: the last value written before kickoff is the closing line, which is both what the analytics want and the sharpest available read on true win probability. Without it a later run could overwrite a settled line with in-play numbers. One row per game in gameodds, overwritten until kickoff, no history kept.

Results

Results land on their own. The nightly cron is the safety net, and the pages call /api/results/refresh themselves, which pulls fresh results whenever a game has kicked off but has no result yet. Hobby crons cannot run more than once a day, so that on-demand call is what keeps things current mid-slate.

Live scores work the same way: while any game is in progress the gameday view polls every 30 seconds. A shorter cooldown on the refresh endpoint means a room full of viewers still costs one upstream fetch per cycle. The admin page remains as a manual fallback.

Notifications

Web Push, so alerts land on a phone's lock screen with no SMS provider and no cost. Generate a VAPID pair once and set NEXT_PUBLIC_VAPID_PUBLIC_KEY, VAPID_PRIVATE_KEY and VAPID_SUBJECT:

node -e "console.log(require('web-push').generateVAPIDKeys())"

Preferences are per device, not per player, so someone can take bust alerts on their phone and nothing on their laptop. Four kinds: a locked game kicking off, a locked game finishing, a rival busting, a rival hitting. Tapping any of them opens that week's live gameday screen.

Alerts fire from state transitions during a results refresh, never from current state, so a result announces itself exactly once however often the refresh runs. Rival alerts are grouped per game rather than per pick — this league picks alike, and one message per pick would mean a game six people locked fires thirty notifications for a single result.

Scoring is all or nothing, so a player carrying a loss is out for the week and nothing further about their locks is sent: not to them, not to anyone else. The bust that eliminated them still goes out. A fifth alert reminds anyone who has not submitted, anchored on the week's real first kickoff rather than a fixed weekday — week 1 of 2026 opens on a Wednesday.

Alert titles are one-liners rather than descriptions, since the title is what gets read on a lock screen. They are drawn from a pool weighted toward whatever is specific about the result — the team that let someone down, a Thursday elimination, a blowout, a one-score loss — and chosen from a per-event seed, so a result picked up by two refreshes always reads the same way while different results spread across the pool. The facts live in the body.

Results are also refreshed from GitHub Actions (.github/workflows/refresh-results.yml) every five minutes during the hours games actually end. Hobby crons run once a day and in-app polling only runs while a page is open, so without it a Thursday night game finishing at 11pm went unannounced until the 4am sweep. The workflow needs CRON_SECRET set as a repository secret.

iOS requires the site to be installed to the Home Screen first. Android and desktop do not. The setup card walks through the Safari steps when it detects an iPhone that has not installed yet.

Backups

.github/workflows/backup.yml dumps the database every night and keeps 30 days as workflow artifacts. The repo is public, so dumps are encrypted with the BACKUP_PASSPHRASE repo secret — keep a copy of it outside the repo, since the artifacts are useless without it. Restore:

gpg --decrypt backup.sql.gz.gpg | gunzip | psql "$DATABASE_URL"

API Routes

Authentication

• POST /api/login - User login
• GET /api/me - Get current user
• POST /api/logout - User logout

NFL Data

• GET /api/week - Get current NFL week
• GET /api/schedule - Get games for a week

Picks

• POST /api/picks/submit - Submit weekly picks
• GET /api/picks/my - Get user's picks
• GET /api/picks/all - Get all picks (after submission)

Scoring

• GET /api/scoreboard - Get season scoreboard

Admin

• POST /api/admin/manual-results - Update game results manually

Results

• POST /api/results/refresh - Pull fresh results for the live week (used by the scoreboard)

Notifications

• POST /api/push/subscribe - Register this browser, or update its preferences
• DELETE /api/push/subscribe - Turn alerts off for this browser
• GET /api/push/preferences - What this browser is signed up for
• POST /api/push/preferences - Send a test alert

Cron Jobs

• POST /api/cron/fetch-schedule - Fetch next week's schedule
• POST /api/cron/fetch-odds - Snapshot this week's betting lines
• POST /api/cron/resolve-results - Update game results and scores

Database Schema

Users

• Fixed set of 6 users (Victor, Mihir, Dakota, Chris, Ryan, Jihoo)

Games

• NFL games with ESPN event IDs
• Season, week, teams, start time, status, winner

Picks

• User picks for each game
• One pick per user per game

Weekly Scores

• Computed weekly scores
• All-or-nothing scoring system

Game Odds

• Moneyline, spread and total per game
• One row per game, refreshed each Thursday before lock

Scoring Rules

1. All-or-Nothing: If all your locks for a week hit, you score one point per lock
2. Zero Points: If any lock misses, you score 0 for that week
3. Pick However Many You Like: Lock any subset of the slate — more locks means more upside and more risk
4. Ties Lose: A lock only hits if the picked team wins
5. No Partial Credit: No points for partial weeks

Time Management

• Picks Window: Monday 9:00 AM ET → Thursday 8:00 PM ET
• Lock Time: Thursday 8:00 PM ET (America/New_York timezone)
• Schedule Fetch: Mondays 9:00 AM ET
• Results Update: Daily 3:00 AM ET

Security

• JWT tokens stored in httpOnly cookies
• Secure cookie settings in production
• Admin routes protected by passcode
• Cron jobs protected by secret headers
• No email/password required (friends-only)

Free Tier Limits

• Vercel: 100GB bandwidth, 100 serverless function executions/day
• Vercel Postgres: 256MB storage, 100 connections
• Vercel Cron: 2 cron jobs, 1000 executions/month

Troubleshooting

ESPN API Issues

If ESPN API fails, use the admin panel to manually enter game results.

Database Connection

Ensure DATABASE_URL is correctly set in Vercel environment variables.

Cron Jobs Not Running

Check Vercel cron job configuration and ensure CRON_SECRET is set.

Authentication Issues

Clear browser cookies and ensure JWT_SECRET is set.

Contributing

This is a friends-only application, but feel free to fork for your own league!

License

MIT License - feel free to use for your own projects.