Fantasy Football Draft Helper

README

About the Project

Fantasy Football Draft Helper is a multi-user draft room built for a 12-team, half-PPR league. It supports a $200 auction across seven paid roster slots, followed by snake rounds, while tracking budgets, rosters, nominations, values, and draft history in real time.

Unlike generic draft tools, projected prices are trained on the league's own official auction history from 2018–2025. The app also includes deterministic AI mock drafts, player usage and scoring analysis, tier-cliff alerts, and live target-price estimates.

Features

Live multi-user auction rooms synchronized through PocketBase realtime events
Auction and snake draft formats in one draft flow
League-specific projected auction values based on historical prices
Live target-price estimates, max-bid guardrails, and budget pressure insights
Deterministic AI mock drafts with per-team profiles
Player rankings, injuries, news, game logs, usage signals, and watchlists
Historical draft analysis across official league auctions
Commissioner-managed leagues, invitations, team assignments, and imports
Installable progressive web app with mobile navigation

Built With

Getting Started

Run the Next.js frontend and PocketBase backend locally.

Prerequisites

Node.js 22.x
npm
A local PocketBase installation

Installation

Clone the repository.

git clone https://github.com/nicholas-fierro/fantasy-auction-app.git
cd fantasy-auction-app

Install packages.
```
npm install
```
Create local environment configuration.
```
cp .env.example .env
```
Update .env if PocketBase does not use the default local address.
```
NEXT_PUBLIC_POCKETBASE_URL=http://127.0.0.1:8090
POCKETBASE_URL=http://127.0.0.1:8090
FANTASYPROS_API_KEY=
```
FANTASYPROS_API_KEY is optional for local development. It enables the FantasyPros comparison panel.
Start the development server.
```
npm run dev
```
Open http://localhost:3000.

PocketBase Setup

PocketBase is required for the app to run. This project expects a local instance at ~/Pocketbase/main by default.

cd ~/Pocketbase/main
./pocketbase serve

PocketBase will be available at http://127.0.0.1:8090.

Canonical migrations and hooks live in this repository:

pb_migrations/ contains collection schemas, indexes, and API rules.
pb_hooks/ contains server-side draft, permission, admin, and rate-limit behavior.

Copy migrations and hooks into the matching directories under ~/Pocketbase/main, then restart PocketBase. PocketBase applies migrations at startup and caches its schema in memory.

[!IMPORTANT] Any schema-changing migration must also be reflected in pb_migrations/1784300000_baseline_full.js. Integration tests compare an instance built from the baseline with one built from the incremental migration chain.

Usage

Pre-draft preparation

Commissioners can refresh draft data from the import view:

Import the FantasyPros half-PPR cheat sheet CSV.
Import the rookies CSV.
Run Sync player IDs so new players receive provider IDs, headshots, injuries, and comparison data.
Run Recalculate Projected Prices after every rankings import because estimates depend on current rank.

Live draft

Create an official auction and invite league members into the shared draft room. Nominations and picks stream to connected clients through PocketBase realtime subscriptions.

Budget guardrails reserve at least $1 for every remaining paid roster slot. Completed auctions are immutable. Undo only removes the latest pick from an active auction and requires confirmation.

Mock draft

Create a mock auction with simulation enabled. When the auction includes the user's team, the local AI engine handles opponent nominations, auction bidding, and snake-round selections using per-team profiles.

Command-line data jobs

Data scripts live in scripts/ and document their supported flags in each file header.

set -a
source .env
set +a
npx tsx scripts/<name>.ts

Standalone scripts do not load .env automatically. Player-stat bootstrap jobs are dry-run-first: sync IDs, repair reviewed identities, sync IDs again, then import game logs. Review every generated report before rerunning without --dry-run.

Architecture

The browser talks directly to PocketBase through the SDK singleton in src/lib/pb-client.ts. Routine reads and writes do not pass through a Next.js server-side data layer.

Authorization: PocketBase API rules are the primary security boundary. Auction, pick, team, and watchlist access is scoped by user, league membership, role, and auction status.
Server state: TanStack Query owns client-side server state. PocketBase realtime subscriptions patch the query cache directly.
Query layer: Hooks in src/hooks/ expose reads and mutations to components.
Authentication: Login uses PocketBase client-side authentication. A server action mirrors the token into an HTTP-only pb_auth cookie for middleware and server actions. Logout and unauthorized responses clear both stores.
Server-only work: CSV imports, auction lifecycle operations, invite signup, session synchronization, and authenticated external-service proxies remain server-side.
UI shell: NavigationContext switches views inside a single-page application shell rather than route-per-view navigation.

Key domain modules:

src/lib/roster.ts — roster construction, league defaults, and max-bid math
src/lib/value-model.ts — historical comparable-player model for projected values
src/lib/estimated-value.ts — live target-price estimates using shared comparable logic
src/lib/draft-insights.ts — tier cliffs, pace, recency, and budget pressure
src/lib/mock-draft/ — deterministic auction and snake simulation engine
src/lib/fantasy-scoring.ts — fantasy scoring derived from raw game-log inputs

Read ARCHITECTURE_DECISIONS.md before changing data flow, authentication, authorization, or the value model.

More detail:

Data Workflows

Project data comes from three categories:

Live services: Sleeper injuries, ESPN news, FantasyPros comparisons, and provider-hosted headshots
Imported snapshots: FantasyPros rankings, nflverse weekly stats and snap counts, provider ID mappings, and private league auction history
Derived data: Projected auction values, target prices, usage signals, scoring totals, tier cliffs, and draft insights

Only official auction prices contribute to historical value estimates. Player game logs join through canonical gsis_id values, never player names.

See docs/data-sources.md for freshness, ownership, and join-key details.

Testing

Run full validation before submitting changes:

npm test
npm run test:integration
npm run build
npm run lint

Additional commands:

npm run test:watch
npx vitest run src/lib/mock-draft/mock-draft.test.ts
npx vitest run src/lib/mock-draft/mock-draft.test.ts -t "test name"

npm run build is the best full type-check. Integration tests start a temporary PocketBase instance and verify that the baseline schema matches the incremental migration chain.

Deployment

The Next.js app is designed for Vercel. PocketBase is deployed separately behind HTTPS.

Production requires HTTPS values for both PocketBase environment variables:

NEXT_PUBLIC_POCKETBASE_URL=https://pocketbase.example.com
POCKETBASE_URL=https://pocketbase.example.com

Production infrastructure and migration procedures are intentionally kept outside this public repository.

License

No open-source license has been added yet. Copyright remains with the repository owner unless a license is added later.

Contact

Nicholas Fierro — @nicholas-fierro