Play in the sandbox! Demo available here
This application is a full stack competition scoresheet generation and management system designed for BJCP sanctioned competitions.
This application is catered toward the flight-based judging session; two or more judges simultaneously evaluating a flight of entries sequentially while filling out scoresheets for each.
Historically, competition judging with paper scoresheets has been a chore - manual scanning and upload of hundreds of scoresheets typically postponed entrants from receiving their feedback for days, and terrible handwriting sometimes made that feedback worthless altogether! On top of that, judges are not always well-versed in all of the BJCP styles and sometimes develop "writer's block" when it comes to descriptors, leading to somewhat bland feedback. This application seeks to address all of those problems:
- Judges fill out scoresheets electronically, so handwriting is not an issue
- Judges have access to sliders to help more accurately provide sensory description without requiring lengthy descriptions
- Judges can easily see BJCP style guidelines for each section, allowing accurate judgement based on style
- Scoresheets are digitally created and collated, allowing quick redistribution to contestants immediatly after competition results are announced
User Account Creation
- New users accounts can be created by navigating to the app home page and clicking the "Register" link in the navbar
Flight Creation
- Logged in users can create new flights by clicking the "Add Flight" button on the main screen.
- Users judging the same flight should enter the same flight number, which should be provided by the competition coordinator
- It is recommended that users judge flights simultaneously
- Flights cannot be deleted once they have been created
Scoresheet Creation
- Once a flight has been created, users may add scoresheets to their flight by clicking the "Add Scoresheet" button
- Entry Number is must be populated for the scoresheet to be saved
- Users may use the tabs to navigate between various scoresheet sections
- Flight posision auto-increments as scoresheets are added, however this may be overwritten
- Once the style and substyle is populated (e.g. "9" and "C"), helpful tooltips on each page will show the BJCP guidelines for the selected style
- Total score is automatically recalculated when section scores are changed
- For first round judging, users may select round advancing entries by clicking the "Mini BOS Advance" button at the top of the scoresheet page
- For final round judging, users may select placed entries by selecting a place option from the dropdown at the top of the scoresheet page
- If two or more users judging the same entry have different scores, a consensus score may be agreed upon and entered at the top of the page. This score will supercede all judges' scores.
- Once the user has completed filling out the scoresheet, they can return to the flights page by clicking "Back to My Flights"
- Scoresheets are automatically saved after any change
Flight Submission
- Once users have completed scoresheets for all entries in a flight and assigned placement / advancement / consensus scores, the flight may be submitted
- Once a flight has been submitted, it cannot be undone by the user
- Admins may undo flight submissions through the admin panel
Scoresheet PDF Generation
- Scoresheets can be downloaded by the user that created the scoresheet in the "Completed Flights" section
- Scoresheet pdf downloads are only available for entries in completed flights
- All scoresheets in a flight may be downloaded by clicking the "Download All" button
- It is recommended to download all completed scoresheets to the user's local device after completion for data redundancy
Admin Panel
- Coming soon!
Development Environment Setup Instructions
Setting up a development enviroment is relatively easy and only requires node and npm to be set up.
- Clone the repository to your development machine and run
npm install - Persistent storage management is handled through Sequelize
- Development environent uses SQLite, which does not require additional database dependency installation
- (optional) Staging environment requires PostgreSQL
- Ensure PostgreSQL is installed and running
- Create a new database with the name
bjcp-scoresheet - Create a user with username
userand passwordpasswordwith read/write privileges enabled
- Run all database migrations by by running
npm run migrate - (optional) Create a development admin account by running
npm run seed- Default username is
admin@scoresheets.org, default password ispassword - Standard accounts can be upgraded to admin level accounts by manually writing a query to update the
user_leveldb field to a value greater than 0
- Default username is
- Start development server by running
npm run debug- (optional) Start staging server by running
npm run staging
- (optional) Start staging server by running
- App can be viewed at http://localhost:3000
Deployment Instructions
Currently, the application is set up to be painlessly deployed to Heroku through github integration. Simply fork the repository, connect your Github account, and deploy the master branch. At least one full-time dyno and one webworker is recommended at a minimum for optimal performance.
Major Dependencies
- archiver - used to zip scoresheet .pdf files together when user requests more than one download
- express - framework used for webserver functionality on back end
- passport - framework used for secure authentication and session management
- sequelize - ORM used for multi-paradigm persistent storage
- pg - Posgres framework for NodeJS
- sqlite3 - Sqlite framework for NodeJS
- puppeteer - utilized in headless configuration to generate .pdf scoresheets from html/css templates
- prettier - automatic pre commit linting and code format
Issues and feature requests are handled through the project issues management tab