FantasyWizard

AI-powered fantasy sports roster, draft, waiver, and trade guidance for Sleeper, Yahoo, and ESPN leagues.

---

Table of Contents

• Overview
• TODO
• Monorepo Structure
• Stack & Architecture
• Quickstart
• Configuration & Environment Variables
• Deploy As A Website
• REST API Reference
• Troubleshooting
• Useful Scripts & Commands
• Decisions & Notes
• Security
• License

---

Overview

FantasyWizard is a fantasy sports assistant for roster management, matchup breakdowns, draft planning, waiver targets, trade building, and advisor chat. Sleeper is the richest current provider; Yahoo and ESPN are supported through their provider-specific flows where their APIs expose enough data.

---

Project Status & Recent Changes (May 2026)

• Grid Layout Improvements: Columns now shrink as needed—panels and cards stay fully contained in their grid tracks even with long content or very narrow screens.
• Conditional Center Column: The middle pane now shows either your roster or league matchups, based on the active tab (never both side by side). Matches current UI/UX best practices.
• Accessibility: Tab toggle buttons use aria-selected for clear screen reader support.
• Live Data Only: All matchups, rosters, and players are loaded dynamically from the API; no mocks.
• Main Development: The active UI lives in frontend/.
• Provider Expansion: Sleeper, Yahoo, and ESPN are the current user-facing providers; the app is moving toward capability-driven provider adapters.

TODO

Provider Foundation

• Keep the user-facing provider list limited to Sleeper, Yahoo, and ESPN.
• Add frontend provider metadata/capabilities for draft and waiver availability.
• Add backend ProviderCapabilities responses so the frontend does not own provider truth.
• Build a backend provider adapter registry for Sleeper, Yahoo, and ESPN.
• Route league discovery, members, and matchups through Sleeper, Yahoo, and ESPN adapters.
• Move Sleeper roster, waiver, draft, and pick logic behind SleeperProviderAdapter.
• Move remaining Yahoo and ESPN roster/draft/pick logic behind matching adapters, returning capability-aware empty results where a feature is not supported yet.
• Normalize provider IDs for league, team, roster, owner, player, pick, and transaction records.
• Add a Maven wrapper so backend builds/tests do not depend on a globally installed Maven binary.

League Data Model

• Add normalized LeagueSummary, LeagueSettings, LeagueScoringSettings, NormalizedTeam, NormalizedRoster, NormalizedDraft, NormalizedDraftPick, and NormalizedTransaction models.
• Detect league type and format: dynasty/redraft, superflex, TE premium, PPR/half/standard, roster size, taxi/IR, keeper rules, playoff weeks, and median games.
• Normalize future draft capital and traded pick ownership once, then reuse it in the draft board, picks modal, trade builder, and advisor prompts.
• Normalize transactions for adds, drops, trades, waiver moves, FAAB, and picks.
• Add a league format/settings view that explains roster/scoring rules in plain language.

Draft Room

• Add draft settings for snake vs linear and mock round count.
• Add lottery draft settings with worst-first, randomized, and manually adjusted order.
• Render selected draft rounds as a compact Sleeper-style pick lane.
• Select the correct Sleeper draft by target season/status and apply draft-specific traded pick ownership.
• Expand draft settings: draft slot/order override, team count, keeper picks, traded-pick overrides, rookie/veteran pool, roster/scoring settings, dynasty/redraft mode, and auto/manual current pick.
• Add completed draft recap with pick-by-pick results, team hauls, positional runs, reaches, values, and best fits.
• Add draft ADP/value context and compare available players against expected pick range.
• Improve draft predictor using each manager's roster needs, prior picks, pick ownership, and positional scarcity.
• Add ESPN and Yahoo draft/scoring/transaction support where their APIs expose enough data.

Team And League Analytics

• Add team value and roster construction pages for every manager.
• Add power rankings using projected points, roster value, depth, future picks, and record.
• Add playoff odds/calculator using schedule, standings, projections, and tiebreakers.
• Add positional statistics: team-by-team strength, scarcity, replacement level, depth gaps, and flex pressure.
• Add team comparison view for two managers across starters, bench, picks, and projected schedule.
• Add league-wide “what changed” view from recent transactions, injuries, waiver moves, and trades.

Player And Market Data

• Build a player value layer that can blend projections, dynasty value, redraft value, ADP, age, position, and news.
• Add player pages with trend charts, news, stats, projections, roster fit, market value, and comparable players.
• Add player comparison with side-by-side value, production, ADP, age, team context, and roster fit.
• Add market movement alerts for value risers/fallers and roster-relevant injuries/news.
• Add automated cross-provider player ID mapping and manual override tools.

Trades

• Upgrade the trade builder to use normalized picks, scoring settings, league type, and team needs.
• Add trade finder: identify realistic trade partners and packages based on roster gaps and surplus.
• Add trade calculator variants for dynasty, redraft, superflex, TE premium, and picks.
• Add trade database/search from normalized completed trades if we store enough historical data.
• Add recent trade volume/context for players so advisor recommendations know market liquidity.

Portfolio

• Add account portfolio view across saved Sleeper, Yahoo, and ESPN leagues.
• Show player exposure across leagues, duplicate assets, risk clusters, and over/underweight positions.
• Add portfolio filters for league, provider, format, team, player, position, value, and injury status.
• Add cross-league recommendations: sell-high spots, waiver targets, roster holes, and playoff pushes.

Advisor Experience

• Feed provider capabilities, league settings, draft settings, transactions, scoring, and future picks into advisor prompts.
• Add focused advisor actions for draft pick, trade finder, power ranking explanation, playoff path, waiver plan, and portfolio review.
• Add explainable confidence and data freshness indicators for recommendations.
• Add “wrapped”/season recap once enough league history and transaction data exist.

Product And Docs

• Refresh README quickstart and architecture to match the current repo: active frontend is frontend/, backend uses Maven/Spring Boot, and old fantasy-frontend/ references should be removed.
• Add screenshots for roster, waivers, draft board, trade builder, and provider setup.
• Document provider capability support for Sleeper, Yahoo, and ESPN.
• Add API contract docs for normalized provider models.
• Add regression tests for draft order, traded picks, provider capability gating, and adapter normalization.

---

Monorepo Structure

/
├─ backend/           # Spring Boot (Java) REST API, caching, logic
├─ frontend/          # React + TypeScript Vite app
├─ docs/              # Architecture notes and provider roadmap

• Subprojects keep their own dependency and build outputs.
• All generated outputs are covered by .gitignore.

---

Stack & Architecture

• Frontend: React + TypeScript (Vite), TailwindCSS, Framer Motion
  • UI features a member list, matchup details pane (shows ALL weekly matchups, fully API-driven), advisor chat.
  • The main fantasy football app is in frontend/.
• Backend: Spring Boot 3 (Java 17), Caffeine cache, REST API, deterministic projections/trade advice.
• Live Data: All matchup screens pull weekly matchups directly from the backend API; no mock matchup data is used anywhere in the UI.
• LLM: Integration optionally enabled (HuggingFace or local Ollama).

---

Quickstart

1. Clone

git clone https://github.com/SpeciLiam/FantasyWizard.git
cd FantasyWizard

2. Start Backend (Spring Boot, Java 17)

cd backend
mvn spring-boot:run         # Run in development mode OR
mvn package                 # Then: java -jar target/*.jar

The backend serves at http://localhost:8080 by default.

3. Start Frontend

cd ../frontend
npm ci
npm run dev

Open your browser at http://localhost:5173.

---

Configuration & Environment Variables

Backend (backend/)

Create/Edit environment variables or set them in src/main/resources/application.yml:

• HF_TOKEN – HuggingFace LLM API token (optional)
• OLLAMA_URL – Ollama base URL (for local LLM, optional)
• app.cors.origins – Allowed frontend origins (default: http://localhost:5173)
• ADVISOR_IP_WHITELIST – Comma-separated IPs/CIDR ranges that bypass the advisor daily limit, e.g. 203.0.113.10,198.51.100.0/24

Frontend (frontend/)

• .env.local or .env (not committed):
  • VITE_API_BASE=http://localhost:8080

No sensitive keys or API tokens are required for basic usage.

---

Deploy As A Website

The repo is set up for a simple public deployment:

• Frontend: Vercel, using the root vercel.json.
• Backend: Render or any Docker web host, using backend/Dockerfile.
• Connection: Set VITE_API_BASE in Vercel to your backend URL.

1. Deploy Backend

Create a Render web service from this GitHub repo:

• Environment: Docker
• Root directory: backend
• Health check path: /actuator/health
• Required environment variables:
  • CORS_ORIGINS=https://your-vercel-domain.vercel.app
  • GROQ_API_KEY=... if you want advisor chat enabled
  • ACCOUNT_SECRET_KEY=... if you want encrypted saved account connections
  • Yahoo/ESPN variables only if enabling those auth flows

The included render.yaml is a starting point. Update the placeholder domains after the first deploy.

2. Deploy Frontend

Create a Vercel project from this GitHub repo. The root vercel.json builds frontend/ and serves frontend/dist.

Set this Vercel environment variable:

VITE_API_BASE=https://your-backend-domain.onrender.com

After deploy, update backend CORS_ORIGINS to the final Vercel domain.

3. Custom Domain

Add your custom domain in Vercel. Then update:

• Backend CORS_ORIGINS
• Yahoo redirect URI, if Yahoo auth is enabled
• Any public docs or screenshots that reference the temporary Vercel URL

---

REST API Reference

All backend endpoints are prefixed with /api.

• GET /api/user/{username}/leagues?season=2025
• GET /api/league/{leagueId}/members
• GET /api/league/{leagueId}/roster/{userId}?week=1
• GET /api/league/{leagueId}/matchups/{week}Returns all matchups for a week. The UI sorts and highlights the selected member’s matchup.
• POST /api/explain (LLM optional)
• POST /api/trades, POST /api/generate/trades (LLM optional)

See detailed shapes and response samples in REST API Reference.

All matchups, roster, and member data in the UI is loaded live from these endpoints—no frontend mock data.

---

Troubleshooting

• CORS Issues: Set app.cors.origins in backend config. Default allows http://localhost:5173.
• open -n "/Applications/Microsoft Edge.app" --args --user-data-dir**="$HOME**/msedge-dev-data" --disable-web-security
• Java Version: Requires Java 17 or later.
• Port Conflicts: Backend default is 8080, frontend is 5173.
• Dependency Problems: Ensure node_modules for UI, run mvn for backend, check .gitignore does not include lockfiles if you want reproducible installs.

---

Useful Scripts & Commands

Backend

cd backend
mvn spring-boot:run        # Development server
mvn package                # Production JAR build

Frontend

cd frontend
npm ci
npm run dev

Run Both Together

On Unix/macOS:

concurrently "cd backend && mvn spring-boot:run" "cd frontend && npm run dev"

---

Decisions & Notes

• All matchups shown in the UI are API-driven and sorted to the top for the selected member.
• No mock player or matchup data is used in the production UI.
• Full monorepo best practices: clear .gitignore, isolated builds per subproject.
• LLM chat and trade advice are optional and off by default.

---

Security

• Never commit secrets: Use .env files locally (all are gitignored except .env.example).
• Frontend does not require any keys by default.

---

License

MIT License (see LICENSE).