Introduction

BBX is a modern, full-stack tournament management platform specifically engineered for Beyblade X competitive play. It streamlines the complexities of running local and regional events by providing automated Swiss pairings, dynamic Top Cut bracket generation, and real-time standings.

The platform is designed to handle the entire lifecycle of a tournament—from registration and seeding to the final championship match—ensuring that organizers can focus on the action while the system manages the logistics.

Key Features

1. Swiss Pairing Engine

BBX utilizes a Swiss-system tournament format to ensure fair competition.

• Automated Pairings: Generates matches based on current win-loss records.
• Advanced Tie-breakers: Calculates Buchholz scores and point differentials automatically to determine precise rankings.
• Dynamic Standings: A public-facing standings page allows participants to track their rank in real-time.

2. Dynamic Top Cut Brackets

Once Swiss rounds conclude, the platform can "cut" to a single-elimination bracket (e.g., Top 4, Top 8, or Top 16).

• Auto-Seeding: Participants are seeded into the bracket based on their Swiss performance.
• Live Visual Brackets: A responsive bracket view that updates as matches are reported.
• Champion Identification: Automatically identifies the tournament winner upon the completion of the final match.

3. Integrated Admin Console

The Admin Console provides organizers with a centralized "command center" for event management:

• Match Reporting: Record scores, point types (Extreme Finish, Burst Finish, etc.), and winners.
• Round Management: Advance the entire tournament to the next round with a single click.
• Participant Oversight: Add, edit, or remove players on the fly during the registration phase.
• Projector Mode: A dedicated view designed to be displayed on large screens at venues, showing current pairings and results.

System Architecture

BBX is built on a high-performance stack to ensure reliability during live events:

• Frontend: Next.js 15+ (React 19) providing a responsive, "app-like" experience for both mobile and desktop.
• Database & Realtime: Supabase handles data persistence and broadcasts live updates to all connected clients.
• AI Integration: Powered by OpenRouter, allowing for future AI-driven match analysis or automated commentary.

Basic Workflow

To host an event, an organizer typically follows these steps:

1. Creation: Use the /create interface to name the tournament and set the "Cut Size" (e.g., Top 8).
2. Registration: Share the tournament URL with players. Admins can manually add participants via the Admin Console.
3. Swiss Rounds: Start the tournament to generate Round 1 pairings. Report scores as matches finish.
4. Advancement: Once all matches in a round are complete, use the "Advance" feature to generate the next Swiss round.
5. Top Cut: After the designated number of Swiss rounds, proceed to the Top Cut to generate the elimination bracket.
6. Conclusion: Report the final match to crown the champion and conclude the tournament.

Data Model Example: Matches

For developers looking to interact with the tournament data, matches are structured to track both progress and specific Beyblade X scoring metrics:

// Example: Structure of a Match object in the BBX system
{
  id: "uuid",
  tournament_id: "uuid",
  participant_a_id: "uuid",
  participant_b_id: "uuid",
  score_a: 4,      // Points earned by Player A
  score_b: 2,      // Points earned by Player B
  winner_id: "uuid",
  stage: "swiss",  // or "top_cut"
  status: "complete", // or "pending"
  bracket_round: 1,
  match_number: 5
}

This structure allows the system to calculate standings and advance brackets programmatically based on the reported winner_id.