docs(agents): describe canonical/per-window split

Update database.md with the canonical/per-window model explanation,
the syncTournamentResults fan-out contract, the check constraint,
and the tennis-Men/Women quirk.

Update domain-models.md to reflect the renamed per-window entities
and the new canonical layer.

Also update the drizzle-kit gotchas section with lessons from the
migration: do not use --custom for renames; FK constraint naming
can mismatch Drizzle convention.

Phase 4 Task 6.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

2026-05-01 23:14:15 +00:00

2.2 KiB

Raw Blame History

Domain Models

Fantasy Draft System

Model	Description
League	Top-level container; has one or more commissioners
Season	One iteration of a league. Status: `pre_draft` → `draft` → `active` → `completed`
Team	Belongs to a season; owned by a user (`ownerId` = UUID → `users.id`)
Draft Slot	Defines draft order for teams in a season
Draft Pick	Record of each pick made
Draft Queue	A team's pre-ordered wish list of participants
Draft Timer	Active countdown for the team currently on the clock
Autodraft Settings	Per-team config for automatic picking

Season status drives UI visibility: draft order shown in pre_draft, draft controls active in draft, etc.

Snake Draft Logic

Draft slots define base order (1, 2, 3…)
Odd rounds go 1→N; even rounds go N→1
currentPickNumber on the season tracks position
server/timer.ts handles autopicks when timer expires

Sports Data System

Model	Description
Sport	Base sport definition (e.g. NFL, NBA); type is `team` or `individual`
Sports Season	A specific rolling window of a sport (e.g. "Tennis June 2026")
Season Participant	A draftable roster entry for one sports season — links to a canonical Participant
Season Template	Reusable configuration for creating league seasons
Season Sport	Junction: links a fantasy season to the sports it covers
Season Participant Result	Final standings/scores for season participants

Canonical Layer (Qualifying-Points Sports)

Golf, tennis, and CS2 rolling windows share real-world data via a canonical layer. See docs/agents/database.md for the schema split.

Model	Description
Participant (canonical)	Real-world player or team (Djokovic, NAVI) — shared across windows
Tournament	Real-world tournament (Wimbledon 2026) — shared across windows
Tournament Result	Final placement in a real-world tournament — entered once at `/admin/tournaments/:id`, fanned out to every linked window via `syncTournamentResults`
Participant Surface Elo	Canonical surface-specific Elo (tennis) — read by the tennis simulator

2.2 KiB Raw Blame History