refactor.md

Refactor Plan: Single Queue Model

Overview

Refactor from separate playing + waiting arrays to a single queue array where the first 2 entries are considered "playing".

Benefits

• Simpler data model: One array instead of two
• Easier reordering: Just reorder within single array (no cross-array moves)
• Less complex logic: No sanitization needed, no moving between arrays
• Cleaner code: Remove effectivePlayingCount, sanitised* variables
• More intuitive: Queue position = array index

---

Files to Modify

1. src/firebase/courtRepository.js - Simplify Firestore operations

Changes:

• Replace playing + waiting with single queue array
• Remove complex sanitization logic from reorderCourtEntrants
• Simplify removePlayerFromCourt (no array transfers)
• Simplify addPlayerToCourt (just append to queue)
• Update advanceCourt to remove first 2 entries
• matchStartTime logic: Set when queue has exactly 2 entries, or when entry is removed and next player is promoted to position 0 or 1

Functions to update:

• initializeCourtIfNeeded(): { queue: [], matchStartTime: null }
• subscribeToCourts(): { queue: snapshot.data().queue || [] }
• addPlayerToCourt():
  • Check duplicates in single queue array
  • Append to queue
  • Set matchStartTime if queue.length === 2
• removePlayerFromCourt():
  • Filter out from queue
  • Set matchStartTime if after removal we have exactly 2 players AND a player moved into top 2
• updatePlayerInCourt(): Find and update in single queue array
• advanceCourt(): Remove first 2 from queue (currently playing), set matchStartTime if new top 2 exists
• reorderCourtEntrants():
  • Takes single newQueue array
  • Remove duplicates (keep first occurrence)
  • Check if top 2 changed to determine matchStartTime

---

2. src/App.js - Update prop passing

Changes:

• Courts state: { queue: [] } instead of { playing: [], waiting: [] }
• Pass queue to Court component instead of players and waiting
• Remove separate handlers for playing vs waiting
• Single onRemovePlayer handler (removes from queue at any position)
• Single onEditPlayer handler (updates in queue at any position)
• Update onReorderEntries to take single queue array

---

3. src/Court.js - Derive playing/waiting from queue

Changes:

• Accept queue prop instead of players and waiting
• Derive: const playing = queue.slice(0, 2)
• Derive: const waiting = queue.slice(2)
• Keep PLAYING_SLOT_COUNT = 2 constant
• Remove separate onRemovePlaying / onRemoveWaiting props → single onRemovePlayer
• Remove separate onEditPlaying / onEditWaiting props → single onEditPlayer
• Update onReorderEntries to pass single reordered queue array
• Update drag-and-drop to work with single queue array (simpler!)
• Remove effectivePlayingCount calculations
• Update renderQueueEntrant to calculate position based on index in full queue

Simplifications:

// Before: complex logic with playing.length checks
const effectivePlayingCount = Math.min(playingCount, PLAYING_SLOT_COUNT);
const positionLabel = section === "waiting" ? index - effectivePlayingCount + 1 : index + 1;

// After: simple index-based position
const positionLabel = index + 1;

---

4. Firestore Schema Change

Before:

{
  playing: [entrant1, entrant2],
  waiting: [entrant3, entrant4, ...],
  matchStartTime: timestamp
}

After:

{
  queue: [entrant1, entrant2, entrant3, entrant4, ...],
  matchStartTime: timestamp
}

Initialization: Since "start fresh" selected, just update initialization code. Existing courts will use new schema on next write.

---

Implementation Order

1. courtRepository.js - Update all functions to use queue instead of playing/waiting
2. App.js - Update state and prop passing to use single queue
3. Court.js - Update to derive playing/waiting from queue prop
4. Test manually - Add players, remove, reorder, advance queue

---

Key Logic Changes

matchStartTime Rules (Simplified):

• Set to Date.now() when:
  • Queue length becomes exactly 2 (first match starts)
  • Top 2 players change (new match starts)
• Set to null when:
  • Queue has < 2 players (no match)
  • Preserve existing time if top 2 players haven't changed

Reorder Logic (Simplified):

// Before: complex sanitization, splitting, cross-array checks
const seenIds = new Set();
const sanitisedPlaying = []; // max 2
const sanitisedWaiting = []; // rest
// ... 40 lines of logic

// After: simple deduplication
const seenIds = new Set();
const newQueue = [];
nextQueue.forEach(entrant => {
  if (!entrant || seenIds.has(entrant.id)) return;
  newQueue.push(entrant);
  seenIds.add(entrant.id);
});

---

Expected Outcome

• ~50-100 lines of code removed
• Simpler mental model: "It's just a queue"
• Easier debugging: One array to inspect instead of two
• Better maintainability: Less state to keep in sync
• Cleaner drag-and-drop: No section restrictions in reorder logic