A Public web service that displays match schedules and results for FRC teams at events using the FIRST Nexus API and The Blue Alliance API.

Features

• View all matches for a specific team at an event
• Real-time match status updates
• Display match results and scoring details
• Calculate and display ranking points earned
• Responsive design suitable for mobile and desktop
• Embeddable widget for use in other websites

Self-Hosting Installation

Important

YOU DO NOT HAVE TO DO THIS! You can visit https://vorel.app and our service is ready to serve you

Prerequisites

• Node.js (v16 or newer)
• NPM or Yarn

Local Setup

1. Clone the repository

git clone https://github.com/1334Robotics/vorel-app.git
cd vorel-app

2. Install dependencies

npm install

3. Create a .env file based on the example

cp .env.example .env

4. Edit the .env file and add your API keys:
   • Get a Nexus API key from FIRST Nexus
   • Get a TBA API key from The Blue Alliance

Real-time Updates Setup (Optional)

Vorel supports real-time match updates via FRC Nexus webhooks for instant notifications instead of polling:

1. Configure the webhook token in your .env file:

   NEXUS_WEBHOOK_TOKEN=your_webhook_token_here

2. Register your webhook endpoint at frc.nexus/api:

   • Webhook URL: https://your-domain.com/api/webhook/nexus
   • Token: Use the same token you set in NEXUS_WEBHOOK_TOKEN
   • Event Type: Live event status (general) or Match status (team-specific)

3. Benefits of webhook setup:

   • Instant updates when match status changes (no 5-second polling delay)
   • More efficient - only updates when there's actual data changes
   • Lower server load and API usage
   • Real-time notifications for teams using your instance

4. Monitoring:

   • View webhook statistics in the admin dashboard at /admin
   • Check endpoint /api/webhook-stats for webhook metrics
   • Check endpoint /api/sse-stats for active connections

Without webhook setup, the system will continue to work using 5-second polling, which is still very responsive.

Usage

Running locally

npm start

The server will start on port 3002 (or the port specified in your .env file).

Access the application by navigating to http://localhost:3002 in your browser.

How to use

1. Enter a team number (e.g., 1334 or frc1334)
2. Enter an event key (e.g., 2025oncmp2)
3. View match schedule and results

Embedding in another website

You can embed the matches display in another website using an iframe:

<iframe 
  src="http://your-server-url/embed?teamKey=1334&eventKey=2025oncmp2&height=600" 
  width="100%" 
  height="600" 
  frameborder="0">
</iframe>

Docker Deployment

Using docker-compose (recommended)

1. Create a .env file with your API keys as described above
2. Run the service using docker-compose:

docker-compose up -d

Using Docker directly

docker build -t vorel-app .
docker run -p 3002:3002 --env-file .env vorel-app

API Documentation

Endpoints

• GET / - Main application page
• GET /embed - Embeddable version of match display
• GET /api/health - Health check endpoint
• GET /api/data-check - Checks if there are new updates to matches data

Query Parameters

• teamKey - Team number (with or without "frc" prefix)
• eventKey - Event key (e.g., 2025oncmp2)
• height - (Embed only) Height of the container in pixels

License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.

Acknowledgments

• The Blue Alliance for match results data
• FIRST Nexus for real-time match status updates