MODAQ

MODAQ (MODerator Assistant for Quizbowl) is an application for assisting moderators with reading and scorekeeping quizbowl matches. It helps track all the events that occur during the match, such as buzzes, substitutions, protests, and more. It also tracks buzz point data and can export it to a QBJ file, a JSON file, and/or TJ/UCSD Sheets.

See the wiki to learn how to use the reader.

Importing

To use MODAQ in your project as an npm package:

1. Add modaq as a dependency to your package.json file:

   npm install modaq

2. In your React file, import MODAQ with:

   import * as Modaq from "modaq";

   Then use the control like <Modaq.ModaqControl />.

3. If you want to export to Google Sheets format, you need to supply your application's client ID and include this in your HTML:

   <script async defer src="https://apis.google.com/js/api.js"></script>

4. If you want to use the packet parser (instead of passing in a packet parameter), you need to include a URL to YAPP.

For details on props, visit the ModaqControl props section of the MODAQ wiki.

Development

Codebase Overview

See the MODAQ Wiki for a more thorough overview of how MODAQ works internally.

Prerequisites

• Node.js (version 14 or higher)
• yarn
• npm

VS Code is recommended as an IDE. If using VS Code, install the Prettier extension for code formatting.

Setup

1. Download the latest release or clone the repository:

   git clone https://github.com/alopezlago/MODAQ.git
   cd MODAQ

2. Install dependencies:

   npm install
   # or
   yarn install

Building

To build the project:

npm run build
# or
yarn build

This compiles TypeScript and prepares the output.

Development Server

To run the development server:

npm run dev
# or
yarn dev

For testing via the Dev server (required for Google Sheets functionality), which requires HTTPS:

1. Add this entry to your hosts file (on macOS/Linux: /etc/hosts, on Windows: C:\Windows\System32\drivers\etc\hosts):

   127.0.0.1 localhost.quizbowlreader.com

   • If using Chrome, you may also need to set the flag at chrome://flags#local-network-access-check.

2. Run the dev server:

   npm run dev
   # or
   yarn dev

3. Open https://localhost.quizbowlreader.com:5173/out

   You can accept the HTTPS certificate or create your own self-signed certificate.

Testing

To run the tests:

npm test
# or
yarn test

Tests use Mocha and are located in the tests/ directory.

Linting

To check for linting issues:

npm run lint
# or
yarn lint

To automatically fix linting issues:

npm run lintFix
# or
yarn lintFix

Demo

To build the demo:

npm run buildDemo
# or
yarn buildDemo

To serve the demo:

npm run serve
# or
yarn serve

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository. and create a feature branch.
   • Alternatively, you can clone this repository, and create a feature branch on this repository directly.
2. Commit your changes to the feature branch.
3. Ensure npm run lint and npm test pass without warnings or failures.
4. Submit a pull request.

AI policy

Because it's unclear whether LLM-generated code can be copyrighted, LLM-generated code should be limited to tests or refactoring of existing code.

License

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