CIS Scouting App

Overview

This app is a modified version of the Black Hawks Scouting app. The app is able to run in either a docker container or some other NodeJS compatible environment. Scouted data can be submitted to a PostgreSQL database (through Knex and Objection) for external management and analysis, or exported as CSV.

Powered by Vue.js and The Blue Alliance.

Features

• Offline app and data storage
• Works with most web browsers
• Data transfer between devices via QR codes. (Requires a HTTPS connection)
• PostgreSQL database integration (SQLite for local development)
• Configurable without code changes by using pre-made widgets (see config.md in docs)

Setup

Prerequisites

• Node.js 24 or newer. (22 is the minimum the dependencies accept.)
• A PostgreSQL server if you want to store scouting data centrally. Local development can use SQLite instead.
• For Docker deploys: Docker, and a Docker Hub account with push access to the image named in the docker-push script in package.json.

Secrets and local configuration

Three gitignored files hold the secrets. All three are compiled into the frontend bundle or the Docker image at build time. Nothing is read from environment variables or volumes while the app runs, so fill them in before building, and always build (including docker build) from a checkout that contains them.

File	Used by	Contents
.env.local	Frontend build	VITE_TBA_API_KEY=<key>, The Blue Alliance read key. Inlined into the browser bundle.
backend/knexfile.ts	Backend server and migrations	Database connection details per environment. The Docker image uses the production block.
imageServerConfig.ts	Frontend build	WebDAV URL and credentials for the pictureupload widget. Only needed if a form uses that widget. Inlined into the browser bundle.

Because the TBA key and the WebDAV credentials ship to every browser that loads the app, use a read-only TBA key and a dedicated WebDAV app password that can only write to the upload folder.

Steps

1. Obtain a Blue Alliance read API key from the account page.
2. Create a file named .env.local in the root folder containing:

   VITE_TBA_API_KEY=your_api_key

3. Install dependencies:

   npm run installPackages

4. Set up the database config. If backend/knexfile.ts does not exist, copy it from the example:

   cp backend/knexfile.example.ts backend/knexfile.ts

   Then edit backend/knexfile.ts. The development block uses a local SQLite file through the better-sqlite3 client and needs no changes. Put your PostgreSQL connection details in the production block (and staging if you use it).
5. Run database migrations. Without NODE_ENV the knex scripts target the development block:

   npm run knex-migrate

   To migrate a PostgreSQL database instead, use the environment-specific scripts:

   npm run knex-migrate:staging
   npm run knex-migrate:production

6. (Optional) If a form uses the pictureupload widget, create imageServerConfig.ts in the root folder. server must be the full WebDAV base URL of the folder to upload into, not just a hostname. For Nextcloud it looks like this:

   export const imageServerConfig = {
     "server": "https://cloud.example.com/remote.php/dav/files/<username>/<folder>/",
     "username": "<username>",
     "password": "<app password>"
   };

Running the App

Development

Start the frontend development server:

npm run dev

In a separate terminal, start the backend server. The server defaults to the production block of backend/knexfile.ts, so set NODE_ENV=development to use the local SQLite database instead:

# Linux/macOS
NODE_ENV=development npm run dev:backend

# Windows PowerShell
$env:NODE_ENV = "development"; npm run dev:backend

• Frontend: http://localhost:5173/
• Backend API: http://localhost:4173/

Production Build

Linux:

npm run build-linux
npm run run

Windows:

npm run build-windows
npm run run

Docker:

# Build and run locally
npm run docker-build
npm run docker-run

# Build and push to Docker Hub (run `docker login` first with an account that can push to the image name in package.json)
npm run docker-deploy

The Dockerfile copies the working directory into the image, so the three secret files from Setup must exist in the checkout you build from. The container sets NODE_ENV=production, runs knex migrate:latest --env production on start, and serves the app on port 4173. It keeps no state of its own; all scouting data lives in the PostgreSQL database named in knexfile.ts, so replacing the container with a newer image does not lose anything.

Database Migrations

Check migration status:

npm run knex-status

Apply pending migrations:

npm run knex-migrate

Configuration

Frontend

Configuring the interface and data fields is easy and codeless! You just need to add widget configurations to a couple JSON files. Refer to config.md in docs for details.

Backend

The backend uses JSON schemas and Knex migrations to define data fields. When updating the scouting form fields:

1. Update the config files in public/assets/ (config-matches.json, config-pits.json)
2. Update the JSON schemas in backend/schemas/:
   • match_scout_entry.schema.json
   • pit_scout_entry.schema.json
   • api_request.schema.json
3. Update the TypeScript types in backend/schemas/ (.d.ts files)
4. Update the models in backend/src/models.ts
5. Update the conversions in backend/src/conversions.ts
6. Create a new migration in backend/migrations/ to update the database schema
7. Run npm run knex-migrate to apply the changes

The naming scheme in config files must be consistent with the schema definitions. The name field should use lowercase with underscores (eg. "Hello There" becomes "hello_there").

Flexibility

Black Hawks Scouting works in your browser and runs anywhere, no matter if you're scouting on a tablet or testing on a computer.

No download is required on any of your scouting devices! Once you visit the app on a device, you can bookmark it or save it to your home screen. It'll continue to work, even offline.

There are no restrictions on what you can use to analyze your data - Black Hawks Scouting exports in a standard format called Comma-Separated Values (CSV). Your team has the option to use anything from custom Python scripts to professional-grade tools like Tableau and Excel.

Ease of Use

Even with its advanced features, Black Hawks Scouting is designed to be approachable by your team's scouters. You can easily navigate within scouting forms with a navigation menu at the bottom of each form.

Black Hawks Scouting also provides a built-in Data Inspector allowing you to view and manage your scouted data, before you download them.

Offline Usage

With internet often being unreliable at competitions, Black Hawks Scouting has the capability to work fully offline by making use of special browser features. Once you load it with an internet connection, it remains available on your device with the same URL, even without an internet connection or download.

Tip: You can use The Blue Alliance data offline too! Once you load match information online from a form's Team Selection page, Black Hawks Scouting caches it in local storage. On subsequent scouting sessions, you can leave the Event Key field blank and press the Load button to use the cached data. This is faster than an online load and doesn't require internet.

Security

The TBA key from .env.local and the WebDAV credentials from imageServerConfig.ts are compiled into the JavaScript bundle in plain text. Anyone who can load the app can extract them, so use a read-only TBA key and a dedicated WebDAV app password limited to the upload folder. The database credentials in backend/knexfile.ts stay on the server inside the image and are never sent to browsers.

The app also supports the security features of your browser, working even with HTTPS, tracking protection, and cookie blocking.

System Requirements

Black Hawks Scouting can work on Windows, macOS, and Linux. In addition, mobile devices with Android and iOS are also supported. The following browser versions are recommended:

• Google Chrome 100+
• Microsoft Edge 100+
• Mozilla Firefox 100+
• Apple Safari 15.5+

Open Source

License

Licensed under the MIT License, see the license document for the full license terms.

Contributing

Contributions are welcome and encouraged! Please feel free to open issues for problems you encounter or feature requests you come up with. If you would like to contribute code, please open a pull request and describe your changes and reasoning for them. Thank you in advance for your help!

Credits

This program uses modified images from https://www.chiefdelphi.com/t/2024-crescendo-top-down-field-renders/447764.