Real-Time Features Guide

Dutchie's Brackets real-time features keep everyone connected and informed during tournaments using WebSocket technology.

Overview

Real-time updates mean:

Instant bracket updates (< 1 second)
No refresh needed - changes appear automatically
Live for everyone - organizers, participants, and spectators
Always in sync - no stale data

How It Works

Technology Stack

WebSocket Server:

Built with Socket.IO
Runs on separate port (3002 by default)
Handles bidirectional communication
Automatic reconnection

Client Connection:

React components connect automatically
Subscribe to tournament-specific updates
Receive events in real-time
Update UI instantly

Architecture

Tournament Organizer              WebSocket Server              Participants
      |                                  |                           |
      |-- Enters match result ------>   |                           |
      |                                  |                           |
      |                                  |-- match_completed ------> |
      |<-- Confirmation ---------------  |                           |
      |                                  |                           |
      |                                  |-- bracket_updated ------> |
      |                                  |                           |

What Updates in Real-Time

Participant Registration

Event: participant_joined

What Happens:

New player joins via invite link
WebSocket broadcasts to all connected users
Participant count updates instantly
New name appears in participant list
Organizer sees notification

Who Sees It:

Tournament organizer
Other participants viewing the page
Anyone watching the tournament (if public)

Use Cases:

Monitor registration progress
Know when to close registration
Welcome new participants immediately

Bracket Generation

Event: bracket_generated

What Happens:

Organizer clicks "Generate Bracket"
Server creates bracket structure
WebSocket notifies all viewers
Bracket view becomes available
First round matches appear

Who Sees It:

All participants
Tournament viewers
Organizer

Use Cases:

Participants see their first match
Can plan arrival time
Know seeding position

Example Flow:

Organizer → Generates bracket
   ↓
WebSocket → Broadcasts event
   ↓
Participants → Auto-redirected to bracket view
   ↓
Everyone → Sees their match assignments

Match Updates

Event: match_updated

What Happens:

Match status changes (PENDING → IN_PROGRESS)
Or scores updated during match
WebSocket broadcasts changes
Match card updates for all viewers
Progress indicators change

Who Sees It:

Players in the match
Tournament organizer
All spectators

Use Cases:

Track match progress
Know when to warm up
Follow tournament live

Visual Updates:

Match status badge color changes
Score updates live
Timer starts (if enabled)
Players see their current match highlighted

Match Completion

Event: match_completed

What Happens:

Organizer enters final result
Winner automatically advances in bracket
Loser eliminated or moves to losers bracket
Next match opponents populate
All viewers see updates instantly

Who Sees It:

Players in completed match
Players in next match
All tournament viewers
Organizer

Real-Time Effects:

Match Result Entered
   ↓
Winner → Advances to next match (bracket updates)
   ↓
Loser → Marked as eliminated or moves to losers bracket
   ↓
Next Match → Players assigned (participants notified)
   ↓
Bracket → Visual connectors update
   ↓
Participants → See next opponent immediately

Use Cases:

Instant bracket progression
No confusion about next matches
Players can prepare for next opponent
Spectators follow tournament flow

Round Completion

Event: round_completed

What Happens:

Last match in round finishes
WebSocket broadcasts round completion
Next round becomes available
Match assignments appear
Break timer starts (if configured)

Who Sees It:

All participants
Organizer
Spectators

Use Cases:

Signal break time
Announce next round
Prepare for upcoming matches

Visual Indicators:

"Round 1 Complete" banner
Next round matches fade in
Progress bar updates
Round navigation enabled

Tournament Status Changes

Event: tournament_status_changed

What Happens:

Organizer changes status (e.g., READY → IN_PROGRESS)
WebSocket broadcasts new status
UI updates across all devices
Available actions change
Participants notified

Status Transitions:

DRAFT → REGISTRATION_OPEN

Registration button enabled for participants
Invite link becomes active
Join form appears

REGISTRATION_OPEN → REGISTRATION_CLOSED

Join button disabled
"Registration Closed" message shown
Participant count locked

READY → IN_PROGRESS

Tournament officially starts
First matches become active
Match entry enabled for organizer

IN_PROGRESS → PAUSED

"Tournament Paused" banner
Current matches can finish
No new matches start

IN_PROGRESS → COMPLETED

Champion announced
Confetti animation (if enabled)
Results page accessible
Tournament archived

Tournament Completion

Event: tournament_completed

What Happens:

Final match result entered
Champion determined
WebSocket broadcasts completion
Celebration UI triggers
Results become permanent

Who Sees It:

All participants
Organizer
All viewers

Visual Effects:

Confetti animation
Champion highlight
Final standings revealed
Celebration banner

Data Available:

Champion name and details
Runner-up information
Complete match history
Final bracket structure
Tournament statistics

Participant Experience

What Participants See

Tournament Dashboard

┌─────────────────────────────────────┐
│ Summer Pool Championship 2025       │
│ Status: IN_PROGRESS (LIVE)         │
│                                     │
│ YOUR NEXT MATCH                     │
│ ┌─────────────────────────────┐   │
│ │ You vs. John Smith          │   │
│ │ Table 3 • Starting Soon     │   │
│ │ [●] Live Updates            │   │
│ └─────────────────────────────┘   │
│                                     │
│ RECENT UPDATES (Live)              │
│ • Mike won Match 5 (2 min ago)    │
│ • Round 2 started (5 min ago)     │
│ • Sarah joined (10 min ago)       │
└─────────────────────────────────────┘

Live Bracket View

Matches update as results are entered
Your position highlighted
Next opponent shown when available
Live score updates during matches
Visual progression through rounds

Notifications

Participants receive real-time notifications for:

Match assignment
Match starting soon (5 min warning)
Opponent change (if rescheduled)
Tournament status changes
Your match result entered
Advancement to next round
Tournament completion

Organizer Features

Real-Time Dashboard

Live Participant Count:

Participants: 12 / 16  [●] Live
[New: Sarah Johnson joined 30s ago]

Active Matches:

MATCHES IN PROGRESS (Live Updates)
┌──────────────────────────────────┐
│ Match 1: Table 1                 │
│ Alice (3) vs Bob (2)             │
│ [Update Score]                   │
├──────────────────────────────────┤
│ Match 2: Table 2                 │
│ Carol vs David                   │
│ [Enter Result]                   │
└──────────────────────────────────┘

Tournament Timeline:

LIVE ACTIVITY FEED
• 09:45 - Match 5 completed (Alice won)
• 09:42 - Match 4 completed (Bob won)
• 09:40 - Round 2 started
• 09:35 - Bracket generated
• 09:30 - Tournament started

Broadcast Controls

Organizers can trigger real-time updates:

Announcements:

Broadcast messages to all participants
System-wide notifications
Status updates

Match Management:

Reassign tables (live update)
Reschedule matches (notify players)
Update match status

Connection Management

Auto-Reconnection

If Connection Drops:

Client detects disconnection
Automatic reconnection attempts (5 retries)
Exponential backoff (1s, 2s, 4s, 8s, 16s)
Auto-rejoin tournament room
Sync missed updates

User Experience:

[WiFi icon with slash] Connection lost
[Spinner] Reconnecting...
[WiFi icon] Connected! Updates synced.

Connection Status Indicator

Always Visible:

Bottom right corner:
[●] Connected (green dot)
[○] Disconnected (gray dot)
[◐] Reconnecting (yellow spinner)

Offline Behavior

What Still Works:

View previously loaded data
See cached bracket
Read tournament details

What Doesn't Work:

Cannot see new updates
Cannot see real-time changes
Cannot see live scores

When Reconnected:

All missed updates sync automatically
Bracket refreshes to current state
No data loss

Technical Implementation

For Developers

Setting Up WebSocket Connection

import { io } from 'socket.io-client';

// Initialize connection
const socket = io(process.env.NEXT_PUBLIC_WS_URL || 'http://localhost:3002');

// Connection events
socket.on('connect', () => {
  console.log('Connected to WebSocket');

  // Join tournament room
  socket.emit('join_tournament', {
    tournamentId: 'abc123'
  });
});

// Listen for updates
socket.on('match_completed', (data) => {
  console.log('Match completed:', data);
  // Update UI
  updateBracket(data);
});

React Hook Example

import { useEffect } from 'react';
import { useWebSocket } from '@/lib/tournament-websocket';

function TournamentPage({ tournamentId }) {
  const { socket, isConnected } = useWebSocket({ tournamentId });

  useEffect(() => {
    if (!socket) return;

    const handleMatchComplete = (data) => {
      // Handle match completion
      console.log('Match completed:', data);
    };

    socket.on('match_completed', handleMatchComplete);

    return () => {
      socket.off('match_completed', handleMatchComplete);
    };
  }, [socket]);

  return (
    <div>
      <ConnectionStatus connected={isConnected} />
      {/* Tournament content */}
    </div>
  );
}

Broadcasting from Server

import { broadcastMatchCompleted } from '@/lib/websocket-broadcast';

// After match result saved
await broadcastMatchCompleted(tournamentId, {
  matchId: match.id,
  winnerId: winner.id,
  winnerName: winner.displayName,
  loserId: loser.id,
  loserName: loser.displayName,
  score: '5-3'
});

Performance Considerations

Optimizations

Client-Side:

Debounced updates (prevent UI thrashing)
Efficient re-renders (React memo)
Selective subscriptions (only relevant events)
Connection pooling (single socket per app)

Server-Side:

Room-based broadcasting (tournament-specific)
Payload optimization (minimal data)
Connection limits (prevent abuse)
Message queuing (handle bursts)

Scalability

Current Capacity:

100+ concurrent tournaments
1,000+ connected clients
< 100ms update latency

Horizontal Scaling:

Multiple WebSocket servers
Redis adapter for Socket.IO
Load balancing across servers

Troubleshooting

Connection Issues

Problem: "Connection Failed" message

Solutions:

Check internet connection
Verify WebSocket server is running
Check firewall/proxy settings
Try different browser
Disable VPN temporarily

Debug Steps:

// Open browser console
socket.on('connect_error', (error) => {
  console.log('Error:', error);
  console.log('Transport:', socket.io.engine.transport.name);
});

Updates Not Appearing

Problem: Not seeing real-time updates

Check:

Connection status indicator (green?)
Joined tournament room?
Page refreshed recently?
JavaScript enabled?

Quick Fix:

Refresh page
Clear browser cache
Check console for errors

Delayed Updates

Problem: Updates appear slow (> 3 seconds)

Possible Causes:

Slow internet connection
Server overload
Network congestion
Client-side performance

Solutions:

Close unnecessary tabs
Check network speed
Restart WebSocket server
Contact support if persistent

Best Practices

For Organizers

Best Practices:

Keep page open during tournament - Ensures you receive all updates and can respond to issues quickly
Monitor connection status - Watch for disconnection indicator and refresh if connection unstable
Use wired connection if possible - More stable than WiFi with lower latency

For Participants

Best Practices:

Keep tournament page open - Get instant match notifications and see bracket updates immediately
Enable browser notifications (if supported) - Get alerts when minimized and never miss a match call
Add to home screen (mobile) - Quick access during tournament with better performance

For Developers

Best Practices:

Handle connection states - Show loading during reconnection, queue updates while offline, sync when reconnected
Implement error boundaries - Graceful degradation and fallback to polling if WebSocket fails
Clean up listeners - Remove event listeners on unmount to prevent memory leaks