MPH — Malahide Performance Handicap

ElectronReactTypeScriptSQLitebetter-sqlite3RechartsVitest

White doves flying around a tree

Overview

MPH is a desktop application for the Race Officer and Handicapper at Malahide Yacht Club. It replaces the spreadsheet that previously drove the club’s performance handicap system with a purpose-built tool.

In performance handicap racing, every boat carries a TCF (Time Correction Factor) that scales its elapsed time so a well-sailed slow boat can beat a badly-sailed fast one. Those numbers have to be re-derived after each series, and the job carries real consequences — a handicap change decides who wins the next race. The spreadsheet made that work hard to audit and nearly impossible to experiment with safely.

The app’s central idea is that the handicapper should see the consequences of an adjustment before committing to it.

What I Built

  • Halsail import — parses the club’s multi-sheet .xlsx exports, matching boats by sail number and detecting duplicates by (series, race number, sail number), so a re-import is always safe.
  • Handicap calculation engine — a pure function implementing the club’s seven-step formula, with three adjustable weights (w_hcap, w_recip, w_pi) exposed as sliders.
  • Review and approve — proposed handicaps next to current ones, with per-boat manual overrides, deltas, and percentage changes; nothing is written until it’s approved as a batch.
  • What-if re-scoring — re-scores past races under the proposed handicaps and shows the re-ranked finish order beside the original, so the handicapper can see exactly who the change would have promoted or demoted.
  • Handicap trends — multi-boat line charts of TCF over time, to spot a boat drifting steadily in one direction.
  • Audit trail — every handicap revision is retained with the reasoning behind the decision, giving the club a permanent record rather than a succession of overwritten spreadsheet cells.

Reverse-Engineering the Formula

The club’s handicap formula existed only as an Excel workbook — a grid of nested cell references with no written specification. Working backwards from the real workbooks, I recovered it as three composable steps:

PI       = (fastest_elapsed_in_race / boat_elapsed_secs) × fastest_boat_tcf
HCAP_PI  = boat_tcf / PI
new_TCF  = w_hcap × old_TCF + w_pi × avg_PI + w_recip × (old_TCF / avg_HCAP_PI)

The subtle part was fastest_boat_tcf. It refers to the boat that set the fastest elapsed time — the scratch boat on the water — not the boat that won on corrected time. The two differ whenever a lower-rated boat takes the handicap win, which is precisely the interesting case. Getting that wrong produces plausible-looking handicaps that are quietly incorrect.

The recovered formula is verified against the club’s real workbooks as the source of truth, and documented as a written spec so the next person doesn’t have to re-derive it from cell references.

Tech Stack

  • Electron 41 with electron-vite — offline-first, no server, data stays on the handicapper’s machine
  • React 18 + TypeScript
  • SQLite via better-sqlite3, with numbered migrations
  • Recharts for the trend charts
  • Vitest for the calculation engine
  • Tailwind CSS, with Light / Dark / System theming

All database access runs in the Electron main process over typed IPC handlers, keeping SQLite off the renderer thread. Handicap values are stored at full REAL precision and rounded only for display — the backend never rounds, because small errors compound across a normalisation pass over the whole fleet.