Buzzpoints

Buzzpoints is a tool that uses a web app to visualize advanced stats for quizbowl tournaments run using MODAQ. The buzzpoints app reads a database file created using the buzzpoint-migrator tool.

Examples of sites that utilize and/or are built via the Buzzpoints toolset include:

• buzzpoints.vercel.app
• College Quizbowl Stats - Detailed Stats
• Film Set Buzzpoints
• 2025 ACF Regionals

Get Started

1. Run your quizbowl tournament, using MODAQ to collect QBJ files for each game.
2. Use the buzzpoint migrator to generate a database file (database.db) from the QBJ files.
3. Clone or download this repository locally.
4. Copy the generated database from the buzzpoint-migrator folder into this repository's data/ folder.
5. Follow the local deployment steps below to visualize your stats on your own machine.
   • The local deployment interface will resemble buzzpoints.vercel.app.
   • If there are any errors, try debugging by checking the migrator folder database generation and/or visualizing the database file manually.
   • If you're unable to fix the error on your own, file an issue.
6. If desired, use Vercel to host the stats online by following the web deployment steps below.

Local Deployment

1. Clone this repository via SSH, HTTPS, or downloading as a zip.

   • Cloning via SSH is recommended, as setting up SSH at this step can save you a lot of time later.

2. Install Node.js and npm on your system if they're not already installed.

   • Node.js version 22.12.0 is the recommended version.

3. Open a bash shell (e.g. Terminal), go to the root directory of your repository, and run npm install.

   • This command will install all the necessary libraries within the node_modules/ folder of your repository.

4. Run the development server locally:

   npm run dev
   # or
   yarn dev
   # or
   pnpm dev

   • You may have to first install Next.js - follow the manual installation instructions.

5. Open http://localhost:3000 with your browser to see the live local deployment.

   • If another local deployment is already running, the process may pick a different local port instead of 3000.

You shouldn't need to modify anything at this point, so if something is broken, double-check your data in the migrator directory.

If you want to debug or develop new features, the source files for the backend are in /src/app/. The live local deployment auto-updates as you edit each file.

Web Deployment

The easiest way to share your buzzpoints publicly is to create an online web app using the Vercel platform by the creators of Next.js.

GitHub Repository

• Once you have verified your site builds properly, commit your changes in your local version of this repository with your sets' database.db file.
• On GitHub, create a private repository.
  • See the Optional Extra Security section for optional additional actions at this step to further protect your repository if desired.
• Push your local repository to the newly created private GitHub repository.
  • There are a number of tutorials for creating, committing, and pushing to a remote repository:
    • GitHub documentation
    • Git SCM tutorial
• After pushing, your repository should look identical to this one, just with an additional data/ folder containing database.db. If your repository looks different, your site will not build properly.

Vercel

It's recommended to create a Vercel account. The simplest way to do this is to use your GitHub account to login to Vercel.

Once logged into Vercel, create a site by importing your private buzzpoints repository as a Vercel project.

Tip

You only have to do this once. The project and site will automatically re-build and update whenever you push a new commit to the private buzzpoints repository.

Tip

If you don't see your repository, click Adjust GitHub App Permissions and use the popup wizard to add the repository to the collection of repositories Vercel has access to.

Important

To password-protect your site, add BASIC_AUTH_PASSWORD as an environment variable with the password as its value, as shown in the image. See the Security for more details.

See the Vercel documentation for any clarification on instructions. You may have to modify the Node.js version of the build to be 20.x in the package (since this is what the package uses).

Security

Password Protection

Tip

The recommended way to secure your site is by password-protecting it using a Vercel Environment Variable.

To password-protect your site, add BASIC_AUTH_PASSWORD as an Environment Variable with the password as its value. It's easiest to do this in the import wizard, as shown in the image above, but you can do this even after the site has already been deployed. See the Vercel documentation for more details.

There is no username for the password protection. Leave the username field blank and fill in the password only.

To remove password protection, delete the environment variable from the Vercel project and re-deploy the project.

For local testing of the password protection, you can set the following environment variable in your shell before starting the app:

export BASIC_AUTH_PASSWORD=mypassword123!

This will create an .env file in the root of the repository containing the password as an environment variable.

Caution

Not only is committing the .env file to your repository's root strongly discouraged, but doing so will password-protect your local deployment only, not the published site. Vercel ignores any .env file in the repository and only references its system's own environment variables.

Optional Extra Security

Note

The following directions are for further security for your site. These steps are no longer explicitly necessary, but can still be taken if you want to be extra careful.

• If your set is not clear and you want to increase the security of your deployment, use a non-easily-guessable name for your private repository.
• E.g., if your set is called 2025 Question Set you could name the repository 2025-question-set-STRING where STRING is a string of your choice:
  • A random alphanumeric string like xyz123
  • A long word or name

Next.js

Buzzpoints is a Next.js project bootstrapped with create-next-app.

To learn more about Next.js, take a look at the following resources:

• Next.js Documentation
  • Learn about Next.js features and API.
• Learn Next.js
  • An interactive Next.js tutorial.

You can check out the Next.js GitHub repository - your feedback and contributions there are welcome!

This project uses next/font to automatically optimize and load Inter, a custom Google Font.

Issues

To request bug fixes and/or new features, file an Issue.

Contributing

To contribute to or develop this toolset, please fork the repository and submit a Pull Request.

Credits

This tool was created by Jordan Brownstein. Ani Perumalla contributed some features after its initial development.

Ryan Rosenberg, Geoffrey Wu, and Ophir Lifshitz have helped debug and develop new features.

William Horton added the password protection functionality.