Product architecture

Plan the assistant, then wire the world

Homefield Fantasy is one brain for two jobs, on every American sport. Season-long and DFS share a player graph, a slate environment, and an explanation layer. They split on the objective: beat your league vs beat a field of 100,000 duplicate lineups.

Jobs to be done

Thursday night: set the season-long lineup before a questionably-active starter ruins the week. Sunday morning — or tip-off, or first pitch — turn a GPP take into unique lineups that still look like that take.

The assistant fails if it hallucinates news, silently double-starts a player, or optimizes DFS as if cash and tournaments were the same contest.

One brain, two objectives

Season-long: maximize expected scoring among players you actually roster, with a penalty for injury and weather. Waivers are replacement-level math against your worst bench seat.

DFS: maximize contest-aware utility under salary, roster construction, correlation, uniqueness, and exposure. GPP utility is ceiling × leverage. Cash utility is floor.

System layers

1. Data plane

▸ Identity: player, team, game, slate
▸ Environment: Vegas, weather, injury
▸ Market: salary, ownership, ADP
▸ Projections: floor / median / ceiling

2. Decision engines

▸ Season ranker (start/sit, compare, FAAB)
▸ Analyst questions hit that compare engine
▸ Pass / game / team stacks
▸ DFS greedy, uniqueness, exposure

3. AI layer

▸ Tool-calling only, no free stats
▸ Contest-aware copy
▸ Explicit uncertainty (Q tags)
▸ Dead session: show reconnect, don't loop

4. Product surfaces

▸ Weekly desk + league sync (this /season)
▸ Start/sit compare + trade fairness
▸ Draft · Keeper/Dynasty · Best Ball (/season/draft|dynasty|best-ball)
▸ DFS studio (this /dfs)

Data you should not scrape

Official DFS salaries and contest entry belong to the site. Plan for CSV upload or a licensed feed. League rosters belong to Sleeper/ESPN/Yahoo APIs with the user's token — never a shared password.

News needs a timestamped source. If the feed is late, the UI must say the injury file is stale rather than sounding confident.

What this optimizer already encodes

Sport-native DraftKings construction, $50k cap, injury haircuts, cash vs GPP utility, optional stacks (QB, game, hitter, line), NFL bring-backs, min unique players, max exposure, and a swap search that will not rerun a locked player.

It is intentionally a fast heuristic, not a full MIP. Slice 2 can swap the engine without changing the UI if the lineup object stays stable.

Build sequence

Slice 0 — this repo

Demo Season desks for NFL, NBA, MLB, NHL, UFC, CFB, CBB, WNBA, MLS, PGA, and NASCAR. Season-long desk, DFS optimizer (NFL + UFC + MLS + PGA + NASCAR switcher), grounded analyst. Enough to argue about product shape without waiting on data contracts — non-NFL Season desks are honest demos with no fake live sync.

Slice 1 — live league (shipping now)

Sync NFL rosters from Sleeper (enter username → pick league — recommended) or CBS Fantasy (paste league page URL → one-click bookmark for their session token → pick team; free OAuth is gone — never a password). Free agents are whoever is not on a roster in that league. CBS sync pulls that league’s lineup slots and scoring rules so start/sit projections match the league (including non-PPR). DFS salaries stay a demo/CSV problem. Other sports still use demo desks.

Slice 2 — live inputs

Sleeper weekly stats, injury tags, 24h trending adds, and this week’s opponent sit on the NFL desk. Connected CBS leagues rescore those stats with the league’s categories (non-PPR, etc.) so start/sit matches the league — demo/Sleeper-only boards still show Sleeper PPR. ESPN supplies spreads, totals, live scores, and kickoff windows. DFS can build Thursday-only, Sunday-early, or primetime pools, or late-swap around games already underway. Other sports remain demo.

Slice 3 — real assistant (shipping)

Tool-gated analyst via /api/analyst/ask. Free Hugging Face cascade (Qwen 72B → 7B → Llama 8B). Rivalry desk tracks You vs Homefield, weekly beat-HF challenges, and visit streaks so managers stay locked in.

Risks to keep on the whiteboard

LLM hallucinated injuries will lose leagues. Tool-gating is not optional.

Site ToS usually forbids bots that enter contests. Export CSV; humans submit.

Projection vendors disagree. Ensemble + show the range, do not pick a cult source.

This is analysis software, not gambling advice. Keep that line in the product copy.