Processor Guide — 2026 Season

Version 3 introduces Supabase as a read-first data layer, clarifies the early runner dual-role rule, and confirms the Wrong Hcp DOS-parity formula is active.

The BAC Handicap App manages 24 weeks of cross-country handicap racing. Runners receive staggered start times based on their handicap. Placings are determined by clock finish time within each distance × gender × age group.

Key terms

Data storage

Target finish times

Complete these steps before the season opens. Most are one-off tasks — once done, weekly processing follows the Race Day workflow.

1. Set up the Google Sheet Confirm the BAC Handicap 2026 sheet is in place. Run the Setup script if starting fresh — it creates all required tabs and seeds the config.
2. Assign bib numbers Check that all registered runners have bib numbers. Use Admin → Assign Bibs for any PENDING runners who registered without an auto-assigned bib.
3. Set opening handicaps Load each runner's opening handicap from the DOS master list. Handicaps are set per runner per distance.
4. Apply the season reset Subtract 2 minutes from every runner's handicap at season start. This levels the field relative to the prior season's finishing handicaps.
5. Test mode verification Run the full race-day workflow against the test sheet before the first live race. Confirm standings, handicap updates, and monthly prize computation all work correctly.
6. Distribute the App Guide Share the App Guide link (/guide) with the committee and regular volunteers so they know how to use the stopwatch and volunteer portal.

Follow these steps in order every race week. Each step builds on the previous — don't skip ahead to Confirm & Save before reviewing.

Step 1 — Enter the stopwatch times

The finish line volunteer uses /stopwatch to record a lap time for each finisher. After the race, they tap Sync to Sheet, which pushes the laps to the Week N Stopwatch tab in Google Sheets. In the main app (Timesheet), click Import Stopwatch to pull those times in.

Step 2 — Enter Early Runners

Early runners started ahead of the main field with a watch timer. Enter each one manually on the Timesheet: enter their bib, start time (their handicap), clock finish time, distance, and mark the entry as Early runner.

Step 3 — Mark Wrong Hcp and Time Trial entries

Step 4 — Enter DNFs

Mark any runner who did not finish as DNF. Their handicap is NOT adjusted — the stored value is kept unchanged. A start time of 0:00 and a finish time of 99:00 are placeholder values stored for DNF entries; they are not real times and are not used in any calculation.

Step 5 — Review Results

Click Review Results. The app runs sanity checks covering duplicates, suspicious times, missing entries, and age group issues. Fix anything flagged before proceeding to save.

Step 6 — Confirm & Save

Click Confirm & Save. The system:

1. Writes to Google Sheets Results go to the current week tab and the main Results tab.
2. Updates each runner's handicap Applies the standard adjustment formula (or DOS-parity formula for Wrong Hcp entries).
3. Recalculates standings Season standings are rebuilt from all saved weeks.
4. Creates per-week backup tabs Week N Results and Week N Handicaps tabs are created automatically for audit purposes.
5. Mirrors results to Supabase All results are written to the Supabase database so the public results page can serve them quickly.

A runner's handicap is their personal start time advantage. It is updated after every race they complete (excluding DNF). There is no separate handicaps table — handicaps are derived from the most recent saved result per (name, distance).

Where to see handicaps

Standard adjustment rules

Wrong Hcp formula

When a runner starts at the wrong time, the system computes an effective finish time as: storedHandicap + (clockFinish − actualStart). The standard adjustment formula is then applied to that effective finish time. Both early-start and late-start Wrong Hcp runners have their handicap adjusted this way.

DNF

No handicap adjustment is made for DNF entries. The stored handicap is kept unchanged regardless of what time appears on the Timesheet.

Runners register via the Google Form and appear in the Runners tab as PENDING until a bib is assigned. Walk-up entrants need to be added manually before their results can be saved.

1. New registrations via Google Form Runners who complete the registration form appear in the Runners tab with PENDING status. Sync the form responses using Admin → Sync Registrations to pull in the latest entries.
2. Assign bib numbers Go to Admin → Assign Bibs, or use the Register tab. Bib numbers are permanent within a season — do not reassign a bib that has already been used in a result.
3. Walk-up entrants Use Admin → Register a Runner to add anyone who didn't fill in the form before race day. Assign them a bib before entering their result on the Timesheet.
4. Name resolution Long hyphenated names may truncate in source data. If a runner's name doesn't match, add the variant to data/name-aliases.csv rather than editing result rows directly.

Test mode lets you run the full processing workflow against a test dataset without affecting any live data. Use it before the first race week and whenever you want to verify a change.

Enabling test mode

Add ?test=1 to the main app URL. The app switches to the test Google Sheet and displays a TEST MODE banner at the top of the page.

Pre-season checklist in test mode

1. Set up the test sheet Populate the test sheet with sample runners and opening handicaps.
2. Import a sample stopwatch CSV Use a CSV with realistic lap times to simulate a full race day import.
3. Process a full week Run through the complete workflow — import, mark specials, review, save. Verify placings, handicap changes, and standings all look correct.
4. Verify monthly prize calculation Use Admin → Monthly Prizes in test mode to confirm the computation and tie-break logic works as expected.
5. Return to live Remove ?test=1 from the URL to return to the live sheet. Confirm the TEST MODE banner is gone before processing any live race.

Volunteers sign up via /volunteer (no PIN required). Their signup is written directly to the Google Sheet roster. Viewing the roster and cancelling signups is also handled from that page.

Points

Volunteers who don't run earn 8 points for that week, assigned to their preferred distance. If a runner does an early start AND volunteers in the same week, they earn the higher of their position points or 8 — whichever is greater.

Viewing the roster

The volunteer page shows current week assignments and the next three upcoming weeks. Use this to see where help is still needed before race day.

Volunteer roles

The season is split into 6 monthly blocks of 4 weeks each. A prize winner is determined per age group × gender × distance for each block.

Prize rules

How to compute prizes

Go to Admin panel → Monthly Prizes → select the block weeks (e.g. weeks 1–4) → click Compute. Review the results before publishing. The system enforces the one-win-per-season rule automatically.

At the end of the 24-week season, follow these steps in order. The season reset must happen after final processing and before new handicaps are distributed.

1. Run final monthly prize computation Compute prizes for the last block (weeks 21–24). Publish and record results.
2. Export standings and results Download season standings and results as PDF/CSV for club records before archiving.
3. Apply the season reset Subtract 2 minutes from every runner's handicap. This is their opening handicap for the next season. Use Admin → Season Rollover or the setup script.
4. Archive the Google Sheet Rename the current sheet to "BAC Handicap 2026 Archive" so it's preserved but not used for live processing.
5. Set up the new season sheet Run the setup script to create a fresh sheet with all required tabs and config for the new season.
6. Update season constants in code Update the SEASON constant in src/lib/supabase-reads.js and src/lib/sheets.js to the new season year/config.

The main app can generate PDF reports for weekly results, full season standings, and monthly prize summaries. These are suitable for printing or distributing to committee members.

Available reports

To generate: go to the Results or Standings tab in the main app → click Download PDF. The report opens in a new browser tab — print or save from there.

Admin Panel

Available at /admin (separate admin password, not the main app PIN). Use for coordinator-level corrections and maintenance outside the normal weekly workflow.

Archive tab

Historical results from the 2025 season are available in the Archive tab of the main app. For reference only — not used in 2026 processing.

Legacy Verify

Available at /legacy-verification. Checks 2025 season data against the DOS scoring engine for consistency. Not used in normal weekly processing.