bracket-creator

This project lets any club or organisation run kendo and naginata tournaments at whatever level of digitization fits the venue, from fully printed to fully online. Pick the mode that matches your equipment:

• Offline. No internet required. Runs entirely on printed brackets and score sheets generated as Excel files.
• Partially connected. Internet is available but there are no display screens. Some printed material is still needed for scoreboards and competitors. Keep every shiai-jo in sync either by sharing the Excel file through Google Sheets, or by running the tournament app, with one device per shiai-jo.
• Fully digital. A complete online setup with on-screen scoreboards and mobile result pages. Needs one device per shiai-jo table, a monitor for each court, and network access for competitors. Organisers still print player tags and numbers.

I've been using this application to organise the London Cup since ~2023. It reflects everything I've learned from running real tournaments and the feedback I've received.

For the kendo tournament guidelines this application is based on, see running_a_kendo_tournament.md. Naginata and Engi-kyogi specifics are covered in the Naginata competitions guide.

Full documentation lives on the documentation website. This README is only a quick overview.

The tournament app

The mobile-app command starts the tournament app server: create competitions, import participants, draw pools and brackets, schedule matches across courts, score in real time, and show results on any device (phone, tablet, laptop, or a TV by the court).

Install bracket-creator first. The Docker image starts the server automatically; with a binary install, start it yourself:

bracket-creator mobile-app --folder ./tournament-data

Then open http://localhost:8080 in your browser.

Highlights:

• Admin console (password-protected): competitions, participants, seeding, draws, scheduling, and scoring.
• Public viewer and court displays: real-time schedule, standings, and brackets for spectators, plus big-screen court displays and a transparent overlay for streaming.
• All formats: Playoffs, Pools + playoffs, League, and Swiss, for individuals and teams (including kachinuki), plus naginata and Engi-kyogi (kata) competitions.
• Excel export: download the results as a workbook at any point during the event.

Start with these guides on the documentation site:

• Choosing your setup
• Your first tournament
• Run a tournament on the day
• Host the tournament app and operating modes and access control
• mobile-app command reference

Excel brackets from the command line

The original core of the project is still there: give it a CSV of participants and it produces fully formatted, print-ready Excel workbooks with pool draws, match schedules, and elimination trees.

# Pools of at least 5 with 3 winners per pool
bracket-creator create-pools -z -p 5 -w 3 -f players.csv -o pools.xlsx

# Straight knockout for teams of 5
bracket-creator create-playoffs -t 5 -f teams.csv -o playoffs.xlsx

See the docs for the full command references and the input format:

• create-pools
• create-playoffs
• Input format
• Tournament formats

Legacy Web UI

bracket-creator serve starts a browser front-end for the same Excel generators, useful if you prefer a form over CLI flags. It is kept for compatibility; the tournament app above is the recommended way to run an event. See the Legacy Web UI guide.

Install

Docker is the recommended way to run bracket-creator on every platform. Homebrew is the other main option, shown below. Linux packages (.deb, .rpm, .apk), pre-compiled binaries, other methods, and upgrade notes are covered in the install guide.

mkdir -p tournament-data
docker run -p 8080:8080 -v "$PWD/tournament-data:/tournament-data" \
  ghcr.io/gitrgoliveira/bracket-creator-mobile:latest

brew tap gitrgoliveira/tap
brew trust gitrgoliveira/tap
brew install bracket-creator

Contribute to this repository

This project adheres to the Contributor Covenant code of conduct. By participating, you are expected to uphold this code. We appreciate your contribution. Please refer to our contributing guidelines for further information.

License

Copyright © 2023–2026 Ricardo Oliveira <oliveira.rg [at] gmail.com>

This is an independent project created and maintained by Ricardo Oliveira in a personal capacity: in his own time and on his own equipment. It is not affiliated with, endorsed by, or owned by any employer, and Ricardo Oliveira is the sole copyright holder.

This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at https://mozilla.org/MPL/2.0/. The full license text is in LICENSE.