brackt/plans/draft-room-implementation.md

Draft Room Implementation Plan

Overview

Build a real-time draft room using Socket.IO for live updates, with snake draft grid, player selection, per-team queue, and chess clock timers.

---

Phase 1: Database Schema & Models

1.1 New Tables

draft_picks

- id (uuid, primary key)
- season_id (uuid, references seasons)
- team_id (uuid, references teams)
- participant_id (uuid, references participants)
- pick_number (integer) - overall pick number
- round (integer)
- pick_in_round (integer)
- picked_by_user_id (varchar) - Clerk user ID
- picked_by_type (enum: 'owner', 'commissioner', 'auto') - who made the pick
- time_used (integer) - seconds used for this pick
- created_at (timestamp)

draft_queue

- id (uuid, primary key)
- season_id (uuid, references seasons)
- team_id (uuid, references teams)
- participant_id (uuid, references participants)
- queue_position (integer)
- created_at (timestamp)
- updated_at (timestamp)

draft_timers

- id (uuid, primary key)
- season_id (uuid, references seasons)
- team_id (uuid, references teams)
- time_remaining (integer) - seconds remaining
- updated_at (timestamp)

1.2 Schema Updates

Update seasons table:

- draft_initial_time (integer) - seconds, default 120 (2 minutes)
- draft_increment_time (integer) - seconds, default 30
- current_pick_number (integer) - track current pick
- draft_started_at (timestamp)
- draft_paused (boolean, default false)

1.3 Model Functions

• createDraftPick()
• getDraftPicks(seasonId)
• getCurrentPick(seasonId)
• addToQueue(teamId, participantId)
• removeFromQueue(queueId)
• reorderQueue(teamId, participantIds[])
• getTeamQueue(teamId)
• updateTeamTimer(teamId, timeRemaining)
• getTeamTimers(seasonId)
• initializeDraftTimers(seasonId) - set initial time for all teams
• autoPickForTeam(teamId) - pick from queue or top EV

---

Phase 2: League Settings Updates

2.1 Add Timer Configuration to Settings Page

• Add fields to "Draft Rounds" card:
  • Initial Time (seconds) - default 120
  • Increment Time (seconds) - default 30
• Update action handler to save these values
• Show in league info panel

---

Phase 3: Socket.IO Setup

Overview

Socket.IO requires access to the HTTP server instance (not just the Express app). The key pattern is:

const server = http.createServer(app);
const io = socketIo(server);
server.listen(port);  // NOT app.listen()

Architecture Decision

Option A: Modify server.js (Recommended)

• Change app.listen() to http.createServer(app) + server.listen()
• Initialize Socket.IO with the HTTP server
• Keep everything in one process
• ✅ Simple, standard pattern
• ✅ Socket.IO and Express share same port
• ✅ Works with React Router v7 SSR
• ❌ Requires modifying server.js

Option B: Separate Socket Server

• Run Socket.IO on different port (e.g., 3001)
• Keep server.js untouched
• ✅ No changes to existing server
• ❌ CORS complexity
• ❌ Two processes to manage
• ❌ Different ports for HTTP and WebSocket

Decision: Use Option A - Industry standard, simpler deployment, better DX

3.1 Server Setup

Step 1: Modify server.js to use HTTP server

File: server.js

Change from:

app.listen(PORT, () => {
  console.log(`Server is running on http://localhost:${PORT}`);
});

To:

import { createServer } from "http";

const httpServer = createServer(app);

// Import and initialize Socket.IO
const { initializeSocketIO } = await import("./server/socket.js");
initializeSocketIO(httpServer);

httpServer.listen(PORT, () => {
  console.log(`Server is running on http://localhost:${PORT}`);
});

Step 2: Create Socket.IO module

File: server/socket.js (use .js not .ts to avoid bundling issues)

import { Server as SocketIOServer } from "socket.io";

let io;

export function initializeSocketIO(httpServer) {
  if (io) {
    console.log("Socket.IO already initialized");
    return io;
  }

  io = new SocketIOServer(httpServer, {
    cors: {
      origin: process.env.NODE_ENV === "production" 
        ? process.env.APP_URL 
        : `http://localhost:${process.env.PORT || 3000}`,
      credentials: true,
    },
  });

  io.on("connection", (socket) => {
    console.log("Client connected:", socket.id);

    // Join draft room
    socket.on("join-draft", (seasonId) => {
      socket.join(`draft-${seasonId}`);
      console.log(`Socket ${socket.id} joined draft-${seasonId}`);
    });

    // Leave draft room
    socket.on("leave-draft", (seasonId) => {
      socket.leave(`draft-${seasonId}`);
      console.log(`Socket ${socket.id} left draft-${seasonId}`);
    });

    socket.on("disconnect", () => {
      console.log("Client disconnected:", socket.id);
    });
  });

  // Store globally for access in route handlers
  global.__socketIO = io;

  console.log("Socket.IO initialized");
  return io;
}

export function getSocketIO() {
  if (!io && !global.__socketIO) {
    throw new Error("Socket.IO not initialized");
  }
  return io || global.__socketIO;
}

Step 3: Add global type definition

File: server/types.d.ts

import type { Server as SocketIOServer } from "socket.io";

declare global {
  var __socketIO: SocketIOServer | undefined;
}

export {};

Step 4: Update tsconfig.node.json

Add server directory to includes:

{
  "include": [
    "server.js",
    "server/**/*.js",
    "server/**/*.ts",
    "vite.config.ts"
  ]
}

3.2 Socket Events (Server)

Listen for:

• join-draft - user joins draft room
• leave-draft - user leaves draft room
• make-pick - user makes a pick (handled via HTTP POST, not socket)
• add-to-queue - add player to queue (handled via HTTP POST)
• remove-from-queue - remove from queue (handled via HTTP POST)
• reorder-queue - reorder queue (handled via HTTP POST)

Note: Write operations (picks, queue changes) should use HTTP POST requests for reliability and error handling. Socket.IO is for broadcasting updates to all clients.

Emit (from server to clients):

• pick-made - broadcast new pick to room
• timer-update - broadcast timer updates (every second)
• current-pick-changed - notify whose turn it is
• draft-started - draft has begun
• draft-paused - draft paused/resumed
• draft-completed - all picks made
• queue-updated - queue changed (only to team owner)

3.3 Client Hook

File: app/hooks/useDraftSocket.ts

import { useEffect, useRef, useState } from "react";
import { io, Socket } from "socket.io-client";

export function useDraftSocket(seasonId: string) {
  const socketRef = useRef<Socket | null>(null);
  const [isConnected, setIsConnected] = useState(false);

  useEffect(() => {
    // Connect to Socket.IO server
    const socket = io({
      path: "/socket.io",
      transports: ["websocket", "polling"],
    });

    socketRef.current = socket;

    socket.on("connect", () => {
      console.log("Connected to Socket.IO");
      setIsConnected(true);
      // Join the draft room
      socket.emit("join-draft", seasonId);
    });

    socket.on("disconnect", () => {
      console.log("Disconnected from Socket.IO");
      setIsConnected(false);
    });

    // Cleanup on unmount
    return () => {
      if (socket) {
        socket.emit("leave-draft", seasonId);
        socket.disconnect();
      }
    };
  }, [seasonId]);

  // Helper to subscribe to events
  const on = (event: string, callback: (...args: any[]) => void) => {
    socketRef.current?.on(event, callback);
  };

  // Helper to unsubscribe from events
  const off = (event: string, callback?: (...args: any[]) => void) => {
    socketRef.current?.off(event, callback);
  };

  return { socket: socketRef.current, isConnected, on, off };
}

3.4 Using Socket in Route Handlers

When a pick is made via HTTP POST, broadcast to all clients:

Example in app/routes/api/draft-pick.ts:

import { getSocketIO } from "~/server/socket.js";

export async function action({ request }: ActionFunctionArgs) {
  // ... validate and create pick ...
  
  const pick = await createDraftPick({...});
  
  // Broadcast to all clients in the draft room
  const io = getSocketIO();
  io.to(`draft-${seasonId}`).emit("pick-made", {
    pick,
    nextPickNumber,
    isDraftComplete,
  });
  
  return json({ success: true, pick });
}

3.5 Testing Socket.IO

1. Start dev server: npm run dev
2. Check console for "Socket.IO initialized"
3. Open browser console on draft page
4. Should see "Connected to Socket.IO"
5. Check server logs for "Client connected: [socket-id]"

3.6 Gotchas & Important Notes

⚠️ Gotcha #1: Import path in route handlers

// ❌ WRONG - This won't work in React Router v7
import { getSocketIO } from "~/server/socket.js";

// ✅ CORRECT - Use relative path or configure alias
import { getSocketIO } from "../../../server/socket.js";

Why: React Router v7 runs server code, but ~ alias typically only works for app code. You may need to configure the import path or use relative imports.

⚠️ Gotcha #2: Client hook creates new connection on every render

The current useDraftSocket hook will reconnect if seasonId changes. This is correct, but be aware:

• Don't call this hook multiple times in the same component tree
• Don't pass a changing seasonId unless you want to switch rooms
• Consider memoizing the seasonId prop

⚠️ Gotcha #3: Event listener cleanup

// ❌ WRONG - Listeners not cleaned up
useEffect(() => {
  socket.on("pick-made", handlePickMade);
}, []);

// ✅ CORRECT - Clean up listeners
useEffect(() => {
  socket.on("pick-made", handlePickMade);
  return () => {
    socket.off("pick-made", handlePickMade);
  };
}, [handlePickMade]);

⚠️ Gotcha #4: Socket.IO path in production

If you deploy behind a reverse proxy (nginx, etc.), you may need to configure the Socket.IO path:

// Client
const socket = io({
  path: "/socket.io",  // Make sure this matches your proxy config
});

// Server (if needed)
const io = new SocketIOServer(httpServer, {
  path: "/socket.io",
});

⚠️ Gotcha #5: CORS might not be needed

Since Socket.IO runs on the same server/port as your app, CORS might be unnecessary for same-origin requests. You can simplify:

// Simpler config if same-origin
const io = new SocketIOServer(httpServer);

⚠️ Gotcha #6: Global storage in development

The global __socketIO pattern works, but in development with HMR, you might get multiple instances. The if (io) check helps, but be aware of potential stale connections during hot reloads.

⚠️ Gotcha #7: TypeScript import in route handlers

// This might cause issues because socket.js is JavaScript
import { getSocketIO } from "~/server/socket.js";

// Consider making it TypeScript with proper types
// Or use @ts-ignore if necessary
// @ts-ignore
import { getSocketIO } from "~/server/socket.js";

3.7 Production Considerations

• Socket.IO will automatically upgrade from polling to WebSocket
• Ensure load balancer supports WebSocket (sticky sessions required!)
• Consider Redis adapter for multi-server deployments (future)
• Monitor connection counts and memory usage
• Set up proper error handling for disconnections
• Consider implementing reconnection logic with exponential backoff

---

Phase 4: Draft Room Route & Layout

4.1 Route Setup

• Create /app/routes/leagues/$leagueId.draft.tsx
• Loader:
  • Verify user access (team owner or commissioner)
  • Load season, teams, draft slots, participants
  • Load existing draft picks
  • Load user's team queue
  • Load timer states
• No action needed (all via Socket.IO)

4.2 Layout Structure

┌─────────────────────────────────────────────────┐
│ Draft Room Header                               │
│ League Name | Status | Commissioner Controls    │
└─────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────┐
│ Draft Grid (horizontally scrollable)            │
│ Team 1  Team 2  Team 3  ...                     │
│ 5:23    4:12    3:45    ... (timers)            │
│ ┌────┐ ┌────┐ ┌────┐                            │
│ │1.01│ │1.02│ │1.03│ ...                        │
│ └────┘ └────┘ └────┘                            │
│ ┌────┐ ┌────┐ ┌────┐                            │
│ │2.03│ │2.02│ │2.01│ ... (snake)                │
│ └────┘ └────┘ └────┘                            │
└─────────────────────────────────────────────────┘
┌──────────────────────┬──────────────────────────┐
│ Available Players    │ My Queue                 │
│ [Search: ____]       │ 1. Player A              │
│ [x] Hide Drafted     │ 2. Player B              │
│                      │ 3. Player C              │
│ □ Player 1 - NFL     │ [Clear Queue]            │
│   EV: 125            │                          │
│ □ Player 2 - NBA     │                          │
│   EV: 118            │                          │
│ ⊠ Player 3 - MLB     │                          │
│   (DRAFTED)          │                          │
└──────────────────────┴──────────────────────────┘

4.3 No Navigation Bar

• Create standalone layout without main nav
• Add "Exit Draft Room" button to return to league page

---

Phase 5: Draft Grid Component

5.1 Calculate Snake Order

• Use existing draft slots for team order
• Generate pick order:
  • Round 1: slots in order (1→N)
  • Round 2: slots reversed (N→1)
  • Round 3: slots in order (1→N)
  • etc.

5.2 Grid Display

• Show team names as column headers
• Show timer under each team name
• Render grid cells with pick numbers (1.01, 1.02, etc.)
• Highlight current pick (border, background color)
• Show drafted participant in completed picks
• Responsive: horizontal scroll on smaller screens

5.3 Pick Cell Component

<PickCell
  pickNumber="1.01"
  round={1}
  pickInRound={1}
  teamId={teamId}
  participant={draftedParticipant}
  isCurrent={isCurrentPick}
  isUserTeam={isUserTeam}
/>

---

Phase 6: Player List Component

6.1 Player List Features

• Display all participants from season sports
• Show: "Participant Name - Sport"
• Show expected value
• Sort by: EV (desc), then alphabetical
• Search/filter by name
• Toggle to hide/show drafted players
• Click to add to queue (if not drafted)
• Visual indicator for drafted players

6.2 Player Item Component

<PlayerItem
  participant={participant}
  isDrafted={isDrafted}
  onAddToQueue={handleAddToQueue}
/>

---

Phase 7: Queue Component

7.1 Queue Features

• Show only current user's team queue
• Display in order (1, 2, 3, ...)
• Drag & drop to reorder
• Remove button for each item
• "Clear Queue" button
• Real-time sync via Socket.IO

7.2 Queue Actions

• Add player → emit add-to-queue → update DB → emit queue-updated to team
• Remove → emit remove-from-queue → update DB → emit queue-updated
• Reorder → emit reorder-queue → update DB → emit queue-updated

---

Phase 8: Timer System

8.1 Timer Display

• Show under each team name in grid
• Format:
  • "M:SS" for times under 1 hour (e.g., "5:23")
  • "H:MM:SS" for times 1 hour or more (e.g., "2:15:30")
• Color coding:
  • Green: > 60s
  • Yellow: 30-60s
  • Red: < 30s
  • Flashing red: < 10s

8.2 Timer Logic (Server-Side)

• When draft starts: initialize all timers with draft_initial_time
• During a team's turn:
  • Their timer counts down every second
  • Other teams' timers remain paused
• When pick is made:
  • Stop countdown for current team
  • Add draft_increment_time to current team's timer
  • Move to next pick
  • Start next team's timer countdown
• Emit timer-update every second to all clients
• When timer reaches 0: trigger autoPickForTeam()

8.3 Auto-Pick Function

async function autoPickForTeam(teamId: string, seasonId: string) {
  // 1. Check queue - pick first item
  // 2. If queue empty, pick highest EV participant not drafted
  // 3. Create draft pick with picked_by_type='auto'
  // 4. Emit pick-made event
  // 5. Move to next pick
}

---

Phase 9: Draft Actions & Permissions

9.1 Making a Pick

• Only current team owner or commissioner can pick
• Click participant in player list (if current turn)
• Validate: participant not already drafted
• Create draft pick record
• Emit pick-made to room
• Update current pick
• Update timers

9.2 Commissioner Controls

• Start Draft button (if not started)
• Pause/Resume button
• Force Pick button (for current team)
• Show in header, only visible to commissioners

9.3 Draft Start Logic

• Can be started manually by commissioner
• Or auto-start when draftDateTime is reached (background job?)
• Change season status to "drafting"
• Initialize timers
• Emit draft-started

9.4 Draft Completion

• When all picks made (picks = teams × rounds):
  • Change season status to "active"
  • Emit draft-completed
  • Stop timers

---

Phase 10: Real-Time Updates

10.1 Client State Management

• Use React state for:
  • Draft picks array
  • Current pick number
  • Team timers
  • User's queue
  • Available participants
• Update state when Socket.IO events received

10.2 Optimistic Updates

• When user makes pick: update UI immediately
• If server rejects: revert and show error
• For queue operations: update immediately

---

Phase 11: Mobile Responsiveness

11.1 Mobile Layout Adjustments

• Draft grid: horizontal scroll
• Stack player list and queue vertically
• Collapsible sections for player list/queue
• Larger touch targets for buttons
• Simplified timer display

---

Implementation Order

1. Phase 1: Database schema & migrations
2. Phase 2: League settings timer config
3. Phase 3: Socket.IO setup (server + client hook)
4. Phase 4: Draft room route & basic layout
5. Phase 5: Draft grid component (static first)
6. Phase 6: Player list component
7. Phase 7: Queue component
8. Phase 8: Timer system (server-side logic)
9. Phase 9: Draft actions & permissions
10. Phase 10: Wire up real-time updates
11. Phase 11: Mobile polish

---

Open Questions / Future Considerations

• Background job for auto-start: How to trigger draft start at draftDateTime? Cron job? Polling?
• Timer persistence: What if server restarts during draft? Store timer state in DB?
• Undo picks: Not in initial scope, but may want later
• Draft history/log: Separate view to see all picks in order?
• Notifications: Alert users when it's their turn? (email, push, etc.)

---

Requirements Summary

User Requirements

• Route: /leagues/$leagueId/draft
• Queue: Per-team, private (stored in database)
• Timer: Chess clock (initial time + increment per pick)
• Real-time: WebSocket (Socket.IO)
• Mobile: Should work on mobile
• Commissioner: Can force picks
• Participant sorting: By EV (desc), then alphabetical
• Search: Filter participants by name
• Toggle: Show/hide drafted participants
• Teams: 6-16 teams typical (12 average)
• Timer config: Configurable per league/season
• Auto-pick: From queue, or top EV if queue empty
• Draft state: "drafting" status
• Start: Auto-start at draft date/time, or manual by commissioner
• Pause/Resume: Commissioner can pause/resume
• Pick log: Track who made each pick (owner/commissioner/auto)
• Grid: Horizontally scrollable
• Player display: "Player Name - Sport"
• Pre-draft: Room viewable before draft starts
• Post-draft: Change status to "active" when complete