About Gridiron Franchise

Project Purpose

Gridiron Franchise is a portfolio project that demonstrates a full-stack, franchise-style football simulation platform. It combines a real data model, a working file-upload and validation pipeline, a probabilistic simulation engine, and a polished sports-broadcast style dashboard UI — built entirely with an original, fictional league so it can be shared publicly without touching any real-world sports IP.

Tech Stack

• ▸ Next.js App Router
• ▸ React & TypeScript
• ▸ Tailwind CSS v4
• ▸ PostgreSQL + Prisma
• ▸ Clerk authentication
• ▸ Zod validation
• ▸ ExcelJS for roster templates & parsing
• ▸ Recharts for radar/data visualization

Roster Upload Explanation

Users download an Excel (or CSV) template pre-built with every column the simulator needs — team info plus 0-100 ratings for every position group. On upload, the file is parsed with ExcelJS, validated row-by-row with Zod (range checks, required fields, position enums, jersey numbers), and checked team-by-team for roster composition warnings (missing QB/kicker, thin offensive line, thin secondary). Users see a full error/warning report and a preview table before anything is written to the database.

Simulation Engine Explanation

The engine in lib/simulation/game-engine.ts is a statistical, drive-based simulator — not a physics engine. Each team's offense, defense, and special teams ratings are derived from its roster (lib/simulation/team-ratings.ts), then every simulated drive resolves probabilistically from the rating differential between the offense and the opposing defense, with home-field advantage, turnover chance, big-play chance, red-zone efficiency, and controlled randomness all factored in. Player-level stats are then attributed to the top players at each relevant position.

Multi-Season Franchise Mode

Once a season is complete, Advance to Next Season on the Season page runs an off-season pass (lib/simulation/franchise-progression.ts): every active player ages a year, ratings drift up or down on an age curve, and some players retire based on age and declining performance. Retired players keep their career stats and are never deleted — they're just marked retired and backfilled with a freshly generated rookie at the same position. Depth charts and team ratings are rebuilt automatically, and a new season gets a fresh schedule and reset standings. A Franchise History list tracks every season's champion over time. Before advancing, you can optionally Run Playoffs— a 4-team single-elimination bracket seeded by regular-season record — and the bracket winner becomes that season's champion instead of whoever simply finished with the best record.

Authentication & Multi-Tenancy

Sign-up and sign-in are handled by Clerk. Every account owns exactly one league — the first time you sign in, a fresh 8-team, 360-player league with a scheduled season is generated just for you. Every API route and page checks the signed-in user before touching the database, so franchises are fully private: there's no shared league, and looking up another user's game, team, or player by ID returns a 404 instead of leaking their data.

Portfolio Value

This project showcases relational data modeling, file parsing and validation pipelines, a non-trivial rules-based simulation algorithm, REST API design, and a cohesive, dark-mode sports dashboard UI — all without relying on a simple CRUD scaffold.

Future Roadmap

• ▸ Trade and free agency simulation