Picklr Guide

Tournament management for pickleball - organizers, referees, players, and spectators.

Roles

Organizer

Create tournaments, register teams, manage matches and courts

/organizer

Referee

Score live matches, control match flow

/referee

Player

/player/register

Spectator

View fixtures, standings, and live scores

/

Tournament Structure

Super Tournament (e.g., "Picklr Championship Series")
  Season (e.g., "Summer 2025")
    Tournament / Category (e.g., "Open Doubles")
      Teams (16 teams, 2 players each)
      Pools (A, B, C, D)
      Rounds (Pool Play, Knockouts)
      Matches (round-robin, then elimination)

Organizer Guide

Step 1: Create a Super Tournament

Go to /organizer → Tournament Set-Up → Create Tournament. Enter a name, description, and add one or more seasons. Note the Super Tournament ID displayed after creation.

Step 2: Create a Category

From Tournament Set-Up, click Create Category. Enter the Super Tournament ID, select the season, and fill in category details (name, location, courts, format). Note the Category ID.

Step 3: Register Teams

Click Register Teams. Download the CSV template, fill in team and player info, then upload. Each row has: Team ID, Team Name, Player Name, Phone, Email, DUPR ID, Gender, Age, Skill Type.

Step 4: Team Check-in

Click Team Check-in, select your tournament, then click each player's Check-In button. Green = all players in, Yellow = partial.

Step 5: Generate Fixtures

Click Generate Fixtures. Upload a CSV with pool/team assignments. This creates matches for the round.

Step 6: Match Operations

Go to /organizer → Match Ops for:

Pool Ops - Manage pools, add/remove teams, generate round-robin fixtures
Court Management - Assign matches to courts, reorder queue
Create Knockout - Set up elimination bracket after pool play
Complete Round - Mark a round as finished

Step 7: Post-Match

Go to /organizer → Post-Match for DUPR reports and the tournament leaderboard.

Referee Guide

Step 1: Sign in

Go to /login and enter your referee credentials. After sign-in you land on /me, which lists every tournament you've been assigned to as a referee under Current, Upcoming, and Past tabs. If you don't see a tournament you expect, ask the chief referee to add you via the tournament_referees assignment.

Step 2: Pick a tournament

On your /me dashboard, find the tournament card and click Score matches. This jumps you to /referee/<tournamentId>/matches — the full match list for that category.

Step 3: Find your match

The match list shows each fixture with its court, scheduled time, pool / round, and current status. Look for the one assigned to your court. Tap (or click) the match row to open the scoring screen for it.

Step 4: Court mode scoring

The court page (/court/<matchId>) is built for tablets at the side of the court:

Start match — tap when the first serve goes up. This sets status to In Progress.
Big +/− buttons — one set per team. Tap + on the team that just scored a point; − if you tapped wrong.
End set — tap when a set is decided. This locks the score, records the set winner, and starts the next set.
Finish match — tap when the match is over. Picklr picks the match winner from sets won and writes status Completed.

Step 5: Sync indicator

The cloud icon top-right shows whether your taps are saved:

Synced (green) — every tap is in the database.
Syncing N (blue) — N taps are queued; they will flush automatically.
Offline (orange) — your phone has no signal. Keep scoring — every tap is safely stored locally and will sync when connectivity comes back. You don't need to wait or retry.

Add the page to your home screen for an installable app that survives signal drops.

Match status reference

Status	Meaning
Scheduled	Not yet started
In Progress	Currently being played
Completed	Finished with a winner
Walkover	One team didn't show up; chief referee resolves manually

Rally points vs side-out (serve) points

Picklr's + / − buttons are scoring-mode agnostic. You can use them for either model — just tap + on whichever team won the rally, regardless of who was serving.

The match length is governed by two tournament-level settings stored on the tournaments row in the database:

points_per_game — default 11; the point total a team must reach to win a set.
win_by_two — default true; if the score reaches 10–10 at games-to-11, play continues until one team leads by 2.
max_sets — default 3; best of N sets.

These values are set when the tournament category is created (in /chief/new or directly in Supabase). Picklr does not currently enforce who is serving, track server numbers (first / second server), or auto-rotate the serve. Side-out enforcement and a server indicator are on the Phase 6 roadmap — until then, the referee is the source of truth for which team scored each rally.

Player Guide

Go to /player/register or use the registration link from the organizer
Fill in your details: Name, Phone, Email, Gender, Skill Level, DUPR ID
Select the tournament and submit
On match day, go to /tournament/playercheckin to check in

Spectator Guide

Go to / (landing page)
Enter the Super Tournament ID (ask the organizer)
Select Season and Category, then click View Tournament
Browse tabs: Fixtures, Standings, Table, Stats, Details

For live streaming overlay: /tournament/overlay?tournament=ID&match=MATCH_ID

How fixtures are generated

The chief referee runs the draw generator from /chief/<id>/draws after promoting CSV-uploaded participants into teams. Picklr supports two formats and turns them into a court-by-court schedule that no team is ever double-booked in.

1. Pool building (round-robin format)

Teams are first sorted by seed (lower number = higher seed; un-seeded teams sort last). Picklr then distributes them into pools using a snake / serpentine algorithm so the strong and weak teams are spread evenly:

16 teams, 4 pools, snake distribution:
  Pool A: seeds 1, 8, 9, 16
  Pool B: seeds 2, 7, 10, 15
  Pool C: seeds 3, 6, 11, 14
  Pool D: seeds 4, 5, 12, 13

The default pool size is 4 teams (configurable via the "Teams per pool" field). Pool count is ceil(teamCount / teamsPerPool). If teams don't divide evenly, the last pools are slightly smaller — they still play full round-robin internally.

2. Match generation

Inside each pool, every team plays every other team exactly once. For a pool of N teams that's N × (N − 1) / 2 matches:

Pool size	Matches per pool
3	3
4	6
5	10
6	15

For single elimination format: teams are sorted by seed, padded with byes to the next power of 2 (4 / 8 / 16 / 32 …), then bracketed in standard 1-vs-N order (1 vs 16, 8 vs 9, etc.). Byes are awarded to the top seeds — they simply skip Round 1.

3. Court scheduling

Once the match list is built, Picklr packs it onto courts in time slots. Each slot is slotMinutes long (default 30 min). The scheduler walks the match list and, for every slot:

Tracks which teams are already "busy" in that slot.
Picks the next match whose both teams are free.
Assigns it to the next available court (1, 2, 3 … up to N courts).
Repeats until either every court is filled or no more conflict-free matches exist.
Advances to the next slot and starts over.

This guarantees: no team plays two matches at the same time, courts are kept maximally busy, and the total day length is roughly (totalMatches / numCourts) × slotMinutes.

4. Preview vs commit

The generator first builds an in-memory preview showing every match with its slot, court, time, and pool. Nothing touches the database until you click Commit draw. On commit, Picklr writes:

pools + pool_teams rows for each pool
One rounds row (the slot/time fields disambiguate ordering)
One matches row per scheduled match with court_number, scheduled_time, and status = scheduled
Updates tournaments.draw_status = 'generated'

Once committed, referees see the matches in their court mode and the public tournament page populates fixtures, standings, and stats automatically.

Tuning tips

More courts → shorter day. Doubling courts roughly halves total slots used.
Slot length should match your real match length including changeover. Pickleball doubles is typically 25–35 min; bump to 40 if your venue has slow changeovers.
Pool size of 4 is the sweet spot — every team plays 3 pool matches before knockouts.
Always seed your teams if you have ratings. Snake distribution only helps if seeds are accurate.

URL Reference

URL	Purpose
`/`	Landing - tournament selection
`/tournament/<id>`	Public tournament view
`/organizer`	Organizer dashboard
`/organizer/tournament-set-up`	Tournament creation
`/organizer/match-ops`	Match operations
`/referee`	Referee portal
`/player/register`	Player registration
`/tournament/playercheckin`	Player check-in
`/tournament/overlay`	Stream score overlay
`/help`	This guide