hermes-skills/skills/devops/python-web-service-deployment/references/fantasy-game-backend-core.md

Fantasy Game Core Patterns — Backend (FastAPI + SQLite)

Database schema

users

• id (int PK), email (unique), phone, display_name, password_hash, created_at

leagues

• id (int PK), name, invite_code (unique 8-char), status (draft/active/closed), season_start (date), season_end (date/null), created_by (FK users), created_at

league_members

• id (int PK), league_id (FK), user_id (FK), draft_order (int), is_commissioner (bool)
• Unique: (league_id, user_id)

regions

• id (int PK), name, emoji, description, prev_year_sightings (int), prev_year_bites (int), prev_year_fatalities (int)

draft_picks

• id (int PK), league_id (FK), user_id (FK), region_id (FK), round (int), pick_number (int), created_at
• Unique: (league_id, region_id) — no duplicates

scores

• id (int PK), region_id (FK), event_type (sighting/bite/fatality), description, source_url, points (int: 2/5/10), event_date (date), verified (bool default false), created_at

user_scores (materialized)

• user_id (FK), league_id (FK), total_points (int)

league_excluded_regions

• id (int PK), league_id (FK), region_id (FK)
• Unique: (league_id, region_id) — a region can only be excluded once per league
• Used when 32 % member_count > 0 at draft start: lowest-performing regions are removed so remaining pool is evenly divisible

Points mapping

sighting=2, bite=5, fatality=10

Snake draft implementation

members = sorted(league_members, key=lambda m: m['draft_order'])
for round_num in range(1, total_rounds + 1):
    if round_num % 2 == 0:
        order = reversed(members)  # Reverse order on even rounds
    else:
        order = members
    for member in order:
        # member picks

Turn enforcement

current_pick_count = len(draft_picks)
current_turn_order = (current_pick_count % member_count) + 1
current_picker = member with draft_order == current_turn_order

Score recalculation (on event)

INSERT OR REPLACE INTO user_scores (user_id, league_id, total_points)
SELECT dp.user_id, dp.league_id, COALESCE(SUM(s.points), 0)
FROM draft_picks dp
LEFT JOIN scores s ON s.region_id = dp.region_id AND s.verified = 1
WHERE dp.league_id = ?
GROUP BY dp.user_id

Excluded region filtering

When querying available regions for the draft board, filter against BOTH draft_picks AND league_excluded_regions:

excluded_rows = conn.execute(
    "SELECT region_id FROM league_excluded_regions WHERE league_id = ?", (league_id,)
).fetchall()
excluded_ids = {r["region_id"] for r in excluded_rows}
forbidden = drafted_ids | excluded_ids

Exclusion pick rejection

excluded = conn.execute(
    "SELECT id FROM league_excluded_regions WHERE league_id = ? AND region_id = ?",
    (league_id, req.region_id),
).fetchone()
if excluded:
    raise HTTPException(status_code=400, detail="This region has been removed from the draft pool")

Performance score for exclusion ordering

ORDER BY (prev_year_sightings + prev_year_bites * 5 + prev_year_fatalities * 10) ASC, id ASC

Lower scores = worse performing regions = first to be removed.

League invite code generation

def generate_invite_code():
    return secrets.token_hex(4).upper()[:8]

Region seeding

Use INSERT OR IGNORE so repeated runs don't error. Seed at least 20+ regions for meaningful draft depth.