Tournament Organizer API

A REST API for creating and managing tournaments, participants, and matches, with support for Elo ratings and bracket visualization.

Tournament Types Supported

• Single-elimination
• Round robin
• Swiss
• League

Features

• Generate randomized matches, supporting byes for the highest ranked players
• Track member Elo scores across matches and tournaments
• Leagues for regularly starting with a fresh Elo score and configurable Elo decay after a period of non-participation
• Generate a bracket graphic for visualizing the tournament

Getting Started

Prerequisites

• Node.js (v14 or newer)
• npm (v6 or newer)

Installation

1. Clone the repository:

   git clone https://github.com/david-torres/tournament-organizer.git

   cd tournament-organizer

2. Install dependencies:

   npm install

3. Set up environment variables (optional):

   Create a .env file in the root directory with the following variables:

   NODE_ENV=development
   DB_USERNAME=your_db_username
   DB_PASSWORD=your_db_password
   DB_NAME=your_database_name
   DB_HOST=localhost
   DB_PORT=5432
   DB_DIALECT=sqlite
   DB_STORAGE=./data/tournaments.db
   PORT=3000
   

   For SQLite (default), you typically only need:

   NODE_ENV=development
   DB_DIALECT=sqlite
   DB_STORAGE=./data/tournaments.db
   PORT=3000
   

4. Initialize the database (optional, if starting fresh):

   npm run init-db

5. Start the API server:

   npm start

   Or:

   node app.js

The API server will be running at http://localhost:3000 (or the port specified in your PORT environment variable).

API Endpoints

Method	Endpoint	Description
GET	/members	Get a list of members
GET	/members/search?name=NAME	Search for a member by name
POST	/members	Create a new member
POST	/tournaments	Create a new tournament
GET	/tournaments/latest	Get the most current active tournament
GET	/tournaments/:id/participants	Get a list of tournament participants
POST	/tournaments/:id/participants	Add a member to a tournament
POST	/tournaments/:id/start	Generate matches to start a tournament
GET	/tournaments/:id/matches	Get the list of matches for a tournament
GET	/tournaments/:id/matches?status=STATUS	Get matches filtered by status (pending/completed)
POST	/tournaments/:id/matches	Create a new match (league tournaments only)
PATCH	/tournaments/:id/matches/:match_id	Update a match (set the winner)
GET	/tournaments/:id/bracket	Get the bracket data for a tournament
POST	/tournaments/:id/league	End a league tournament
POST	/tournaments/:id/decay-elo	Decay Elo scores for a league

Bracket Visualization

You can get a JSON, HTML, or PNG representation of the tournament bracket by calling:

JSON (default)

GET http://localhost:3000/tournaments/:id/bracket
GET http://localhost:3000/tournaments/:id/bracket?format=json

HTML

GET http://localhost:3000/tournaments/:id/bracket?format=html

PNG

GET http://localhost:3000/tournaments/:id/bracket?format=image

Running the Simulation Script

You can run the simulate-tournament.js script to simulate the entire flow of adding members, creating a tournament, participants joining, generating matches, and randomly assigning winners until the tournament is complete. Helpers have been added to package.json and can be run using npm:

Single Elimination:

npm run sim-single-elim

Round Robin:

npm run sim-round-robin

Swiss:

npm run sim-swiss

League:

npm run sim-league

AI Disclosure

A large amount of this code was generated by ChatGPT (GPT-4). That said, it was pretty buggy and broken and I had to fix it up a fair amount to get it usable. See the prompt.

License

This project is licensed under the MIT License. See the LICENSE file for details.