Whether it’s the Super Bowl or a regular Sunday game, Football Squares is a classic way to make watching NFL games more fun. I built Football Squares — a full-stack web application that handles everything from player registration to winner payouts — to run these games for friends and family without relying on third-party platforms.
Here’s a look at what it does, how to run it, and where to find the source.
What Is Football Squares?
Football Squares is a 10×10 grid game. Each square on the board corresponds to a combination of the last digit of each team’s score. Players claim squares before the game, random numbers are assigned to the rows and columns, and winners are determined at the end of each quarter based on the scoreboard.
This application handles the full lifecycle:
- Players register, browse active games, and claim squares from a live board
- Admins create games, pull in real NFL matchups from the ESPN API, assign random numbers, record scores, and track payments
Features
For Players
Registration & Login
- Secure account creation with password strength requirements (12+ characters, mixed case, digits)
- Session-based authentication with HTTP-only cookies
Game Browser
- Browse all active games at a glance
- Each game card shows the matchup, price per square, and current status (open, locked, or completed)
Interactive Game Board
- A live 10×10 grid that auto-refreshes every 5 seconds
- Color-coded squares:
- Green — available
- Blue — yours
- Gray — claimed by another player
- Gold border — paid
- Gold badge — a winner square
- Random numbers (0–9) appear along the edges once assigned by the admin
- Set a custom display name for your squares (shown on the board instead of your username)
- Printable board layout for game-day display
My Squares Dashboard
- See all your squares across every game
- Breakdown of how much you owe and how much you’ve paid
For Admins
Game Management
- Create games manually or load upcoming NFL matchups from the ESPN API (with a 5-minute cache)
- Set team names, game date, and price per square
- Assign random numbers to the board (one-time, irreversible — keeps it fair)
- Change game status: open → locked → completed
- Delete games
Score Entry & Payouts
- Enter scores quarter by quarter (Q1–Q4) plus final
- The application calculates the winning square for each period automatically
- Payout amounts display at 20% of the full board value per quarter
Payment Tracking
- Per-game payment summary: who owes what, how much has been collected
- Mark individual squares or all squares for a user as paid in one click
- Full cross-game payment overview per user
User Management
- View, edit, and delete user accounts
- Promote or demote admin privileges
- Reset passwords on behalf of users
Security Highlights
- Passwords hashed with bcrypt
- Rate limiting on login (10/min), registration (5/min), and square selection (100/30 min)
SELECT FOR UPDATEdatabase locking prevents race conditions on square selection- XSS-safe custom display names (HTML-escaped, 50-character limit)
- Audit logging for logins, square changes, payment updates, and admin actions
Running It
Quick Start with Docker Compose
The easiest way to run Football Squares is with Docker Compose. Pull the latest production images and start the stack:
# Create an env file
cat > .env <<EOF
SECRET_KEY=$(openssl rand -hex 32)
CORS_ORIGINS=http://localhost
EOF
# Grab the production compose file
curl -O https://git.dirtymindsinc.net/jwerle/football-squares/-/raw/main/docker-compose.production.yml
# Start it up
docker compose -f docker-compose.production.yml up -dThe frontend will be available on port 80.
Create an Admin Account
docker compose -f docker-compose.production.yml exec backend \
python create_admin.py <username> <email> <password>Container Images
Production images are published to Harbor on every tagged release and are signed with cosign for supply-chain integrity.
| Service | Image |
|---|---|
| Backend | harbor.dirtymindsinc.net/public/football/backend:latest |
| Frontend | harbor.dirtymindsinc.net/public/football/frontend:latest |
Pull them directly:
docker pull harbor.dirtymindsinc.net/public/football/backend:latest
docker pull harbor.dirtymindsinc.net/public/football/frontend:latestVerify a signature with cosign:
cosign verify \
--key <cosign-public-key> \
--insecure-ignore-tlog \
harbor.dirtymindsinc.net/public/football/backend:latestTech Stack
| Layer | Technology |
|---|---|
| Frontend | React, React Router, Axios |
| Backend | Python, Flask, SQLAlchemy |
| Database | SQLite (persisted via Docker volume) |
| Auth | Session cookies, bcrypt |
| CI/CD | GitLab CI, kaniko, cosign |
| Registry | Harbor |
Source Code
The full source is available on GitLab:
git.dirtymindsinc.net/jwerle/football-squares
Found a bug or have a feature request? Open an issue:
Contributions, feedback, and forks are welcome. Whether you’re hosting a Super Bowl party or just making Sundays a little more interesting, Football Squares is ready to run.