2nd & 11 · V2 integration assessment

Data Becomes Experience

A page-by-page map for turning the V1 Worker’s normalized Balls Don’t Lie data into responsive V2 visuals, alerts, evidence, and motion without creating a second scoring engine or exposing provider credentials.

Worker remains authorityNo direct browser-to-BDL callsLeague rules recalculate pointsExact events onlyReversible waves

Non-negotiable architecture

One truth, richer presentation

BDL enriches the existing server pipeline. V2 renders normalized records and never decides what the official fantasy score should be.

ProviderBalls Don’t LieGames, status, clock, plays, standard and advanced stats, availability, projections, rankings, ADP and selected market context.

AuthorityV1 WorkerAuthenticates, rate-limits, caches, normalizes identifiers, applies fallback rules, records revisions and protects secrets.

League truthD1 + Ledger2nd & 11 scoring rules calculate fantasy points. Provider fantasy totals are comparison data only.

DeliveryEnvelope + PushVersioned data, five timestamps, freshness, revision, event identity and replay-safe delivery.

ExperienceV2 ControllerDeduplicates events, prioritizes alerts, applies motion preferences, and renders the accepted V2 surfaces.

Canonical

Fantasy scoring

Raw statistics flow into 2nd & 11 league rules. BDL’s fantasy totals never replace the active scoring configuration.

Corrections create ledger revisions
Provisional state stays visible
Final reconciliation remains server-owned

Protected

Availability

Emergency substitution remains limited to Out, Inactive, or IR while the starter’s game is live, halftime, or delayed.

No client inference from missing data
Always display source and freshness
Keep reserve ordering separate from eligibility

Forbidden

No approximation

Passing first downs, unavailable kick-distance splits, and any field the feed cannot attribute exactly remain excluded.

Null means unavailable, not zero
No synthetic play events
No motion from unverified deltas

Freshness contract

Five timestamps stay visible

Each stage answers a different question and lets V2 diagnose provider lag separately from backend, network, or render lag.

01Event wall-clock

02Provider observed

03Backend received

04Normalized

05V2 rendered

Approved V2 surfaces

Page experience map

Existing routes are reused first. Small backend extensions are requested only when the current response cannot support an exact experience.

Game Day

Event stream

/api/matchup · /api/insights · /api/live/replay

Score ribbons, clock changes, play drops, scoring bursts, reaction prompts and correction notices. Exact event ID and revision drive animation once.

Home

Reuse

matchup + news + availability

Live matchup changes and material roster alerts surface in the command center; low-value feed noise stays out.

My Team

Provenance

/api/lineup · /api/schedule · team week

Availability badge, source, freshness, current points and projected points support reserve ordering without changing substitution rules.

Players + Profile

Metrics

/api/players · /api/players/:id

Standard and advanced measures show source, sample size and freshness. Projection, ranking and ADP remain comparison signals.

Stats

Envelope

/api/stats

League-scored production plus raw standard and advanced fields. Missing metrics remain honestly blank and explainable.

Season

Separated

/api/season

Fantasy standings remain D1 truth. NFL standings and schedule context may enrich matchups but never alter league rank.

Challenges

Evidence

challenge services + canonical events

Only server-authoritative normalized fields settle a challenge. Revisions visibly reopen or correct a provisional result.

Front Office

Evidence

/api/front-office/recommendations

Decision cards cite provider, observation time, freshness and sample. Advanced metrics and projections support, never execute, decisions.

Trades

Advisory

/api/trades · /api/trades/preview

Form, usage, projection and availability enrich player evidence. Roster capacity, locks and execution remain league-authoritative.

Draft

Comparison

draft status + queue + picks

Rankings, ADP, projections and DFS context improve player comparison but never decide ownership or draft order.

News + Social

Context only

/api/intelligence/news · social APIs

Verified play events can seed contextual system posts and reactions. BDL is not the authority for user messages or editorial text.

Data Operations

Control plane

/api/data-operations

Provider authority, reserve capacity, lag stages, stale/fallback state, revision flow and identifier mapping become visible.

V2-owned motion

Exact live-event triggers

Every event is bounded, deduplicated and replay-aware. Reduced motion swaps travel or particles for concise static emphasis.

Normalized event	V2 response	Safety rule	Reduced motion
Touchdown	Score pulse, touchdown wordmark, reaction prompt	Once per eventId + revision	Static score highlight
Interception	Possession-flip banner and interception reaction	Confirmed play only	Banner without travel
Turnover on downs	Drive-state flip and contextual system post	Ignore provisional duplicate	Color and text change
Big play	Player drop-down, yardage pulse and optional crowd reaction	Configured threshold; exact yards	Short live tile
Sack / field goal	Compact play card and fantasy delta if applicable	League rules calculate delta	Compact card
Correction	Previous value rolls to corrected value with source label	New revision required	Correction badge
Final	Game-over treatment, final scores, challenge settlement queue	Final state from Worker	Static final ribbon

Queue behavior: V2 keeps a bounded priority queue, allows a small number of simultaneous effects, cancels the oldest low-priority effect when full, and never replays an already-rendered event unless the user intentionally enters Replay mode.

Small backend handoff

What V1 may need to expose

These are additive contract extensions, not a new provider path and not authorization to change V1 during this checkpoint.

Extension A

Provider envelope

Add consistent metadata to high-value reads while preserving their existing data shapes.

schemaVersion and dataType
provider and authority
season, week, revision and stale
providerObservedAt, backendReceivedAt, normalizedAt

Extension B

Normalized plays

Expose exact play events through the existing live stack or a narrowly scoped event endpoint.

eventId, gameId, revision and type
teamId and playerIds
occurredAt, yardline, gain and score delta
game state, authority and replay flag

Extension C

Advanced evidence

Extend player and stats reads with labeled advanced fields rather than shipping raw provider payloads to the browser.

source and sample size
availability and freshness
projection/ranking comparison label
null-safe field completeness

Envelope shapeProposed additive metadata

{
  "meta": {
    "schemaVersion": "1",
    "dataType": "game-events",
    "provider": "balldontlie",
    "authority": "primary",
    "season": 2026,
    "week": 4,
    "providerObservedAt": "...",
    "backendReceivedAt": "...",
    "normalizedAt": "...",
    "revision": 17,
    "stale": false
  },
  "data": [ /* normalized application records */ ]
}

Rate guard: plan for the documented 600 requests per minute with a 180-request reserve. Critical live traffic targets 10–15 seconds; availability refreshes no more than once per minute; reference data remains cached longer.

Reversible migration

Implementation sequence

Each wave can be disabled independently and must preserve V1 canonical scoring, fallback behavior and rollback controls.

Data foundation

Shared envelope parser, freshness model, render timestamp telemetry and event dedupe policy. No visual behavior change.

Contract tests first
Unknown schema fails safely
Feature flag off by default

Game Day events

Consume normalized live events through a bounded animation controller. Replay uses the same IDs with an explicit replay context.

Exact triggers only
Reduced-motion parity
No ledger mutation

Surface enrichment

Add advanced evidence, freshness and provenance to Players, Stats, Front Office, My Team and Trades.

Null-safe rendering
Sample labels
No hidden approximations

Market context

Introduce projections, rankings, ADP, odds, props or DFS context only inside separately approved user workflows.

Comparison, not truth
Explicit labels
Default-off exposure

Operations

Complete provider health, mapping coverage, rate reserve, lag-stage and fallback visibility in Data Operations.

Actionable alerts
Rollback status
No secrets in UI

Rollback: disable V2 event motion first, then BDL-enriched display fields, while keeping the V1 Worker, D1 ledger and existing provider fallback paths authoritative and intact.