← All work

GVRAT

2020 – now

Homepage of gvrat.racing, November 2026: The Transcon, 3,361 miles in five regions, with 1,649 runners, 2,307,716 miles logged, 24 countries and 208 coast-to-coast finishers, beside the route across the United States

GVRAT began in spring 2020 as a virtual race across Tennessee, logged one run or walk at a time. Six years later it is the Great Virtual Race Across The States: each summer covers one region of a 3,361-mile line from the Atlantic to the Pacific, and runners who finish all five regions have completed the Transcon. I have built and run its systems since the first day.

This is the engineering view: the 2026 race dashboard, the move off WordPress, the rules, the pipeline and how the numbers were checked. The full story of the rebuild, with before-and-after screenshots, is in the post Goodbye, WordPress: rebuilding GVRAT from the ground up.

At a glance

  • Rebuild: About 10 days, with co-race director Steve Durbin, from the first Transcon commit on 30 October 2026 to the new site, archive, certificates and emails all live
  • Lifetime: 21,500 runners and 18,180,242 miles since 2020
  • Transcon: 1,649 runners, 476,704 activities, 24 countries and 215 finishers so far
  • Audit: 4,116 of 4,116 registrations and 473,270 of 473,270 activities matched RunSignup’s own export
  • Safety net: a deploy only goes live when its tests pass: 68 browser tests on the website, and on the Transcon 30 browser tests, 120 pipeline tests and 1,656 checks on the published data
  • Privacy: 0 personal details published

The 2026 race dashboard

Live at dashboard.gvrat.racing. It runs entirely on free tiers, so hosting costs nothing.

It replaced a manual workflow in Google Sheets and WordPress Ninja Tables with a fully automated pipeline for about 500 runners over a 153-day race.

Engineering highlights

  • A fair daily cutoff: the day closes at 12:00 UTC, when the last time zone on Earth finishes its day, so every runner worldwide has had the same number of complete days to log miles.
  • Two simulated characters: the Gingerbread Man always stays one mile ahead of the leader, and the Buzzard moves at exactly the pace needed to finish on the last day.
  • Privacy by design: personal data is removed before anything is published as public JSON.

Front end

  • Next.js 16 (App Router), built as a fully static site, so there is no server at runtime.
  • React 19 and TypeScript.
  • Tailwind CSS v4, with a documented design system of tokens and component patterns.
  • Leaflet and React-Leaflet for an interactive map of the 679-mile course, with a pin for every runner; Leaflet.markercluster groups the 490+ pins.
  • TanStack Table v8 for a leaderboard you can sort and filter by name, bib, gender and country.
  • pdf-lib and fontkit to generate finisher certificates as PDFs in the browser.
  • A static page for every runner, each with its own progress view, built with generateStaticParams.

Data pipeline

  • Python 3.12 pulls in the data and does the calculations.
  • Pydantic v2 defines and checks the shape of the data.
  • Requests calls the RunSignup REST API.
  • gpxpy reads the GPS course file and finds where each runner is along the route.
  • Pluggable data sources (the RunSignup API or CSV) sit behind one shared interface.
  • pytest for tests, and uv to manage dependencies.

Automation

  • GitHub Actions runs the pipeline every day on a schedule, then commits the updated data back to the repository.
  • Cloudflare Pages rebuilds and redeploys the site on each commit.
  • JSON files in git act as the database, and daily snapshots keep a full history of the race.

The 2026 rebuild: leaving WordPress

The homepage, year by year

The first race in 2020 ran on vacationwithoutacar.com, and from 2021 on gvrat.racing. Each May the homepage changed for the new race, from Tennessee to the Great Virtual Race Along The Trace, and then across the United States. Until this autumn, it was still the same WordPress site.

vacationwithoutacar.com in May 2020: Great Virtual Run Across Tennessee over a map of the route across the state, with the line “Last update 2020-05-07 06:17 UTC” and a link to the interactive tracking search

2020 The first race, on vacationwithoutacar.com

The 2021 gvrat.racing homepage banner: two runners, rats and the Gingerbread Man inside the outline of Tennessee against a pink evening sky, with a bat and a vulture’s claw above and the line “Run run run, as fast as you can, you can’t catch me, I’m the Gingerbread Man”

2021 The homepage banner, on gvrat.racing

gvrat.racing in 2022: an illustration of The Great Virtual Race Across Tennessee 1000K, with runners, a dog, the Gingerbread Man and a vulture along the outline of Tennessee, above GVRAT 2022 registration links

2022 Across Tennessee, 1000K

gvrat.racing in 2023: GVRAT 2023, May 1 to August 31, the Great Virtual Race Along The Trace, with USA and non-USA sign-up buttons over a photo of a runner’s shoes

2023 Along The Trace

gvrat.racing in 2024: a map of the United States with the red Transcon route and the title Great Virtual Race Across The States 2024

2024 Across the States begins

gvrat.racing in 2025: Great Virtual Race Across The States 2025 over the route map, marked Transcon Region 2

2025 Transcon Region 2

gvrat.racing in 2026, the last WordPress version: the GVRAT 2026 logo over a road map of the 2026 route

2026 The last WordPress homepage

The new gvrat.racing, November 2026: the Transcon, 1,649 runners and 2,307,716 miles logged, with the route across the United States

Now The new site, built with Astro

2020 and 2022 to 2025 are from the Internet Archive's Wayback Machine: 8 May 2020, then each June. The archived 2021 page lost its styles, so 2021 shows its homepage banner.

The problem

The old gvrat.racing was a WordPress site on shared hosting that had grown one hurried page at a time. The race had outgrown it:

  • Results were copied in by hand. Every update meant exporting from RunSignup, cleaning a spreadsheet and pasting it into a table plugin.
  • The Transcon had nowhere to live. A runner’s journey spans five years and several registrations, but every page on the site was about one year.
  • Nobody could see the whole picture, including the race directors. Who had finished which region, and whose medal had shipped, lived in spreadsheets on our own computers.

Three questions shaped the work: what does a runner come to find out (usually where do I stand?), what do Steve and I need to stop doing by hand, and what has to be true for runners to trust the numbers.

What I built

Four pieces, linked together and designed as one site.

  • gvrat.racing: a static Astro site. The home page leads with whatever is happening now, and results for every year since 2020, the FAQ, guides, Laz’s writing, the lifetime miles list and the Hall of Fame each have one place.
  • The Transcon dashboard: every runner on one map, a timeline of the five regions, a searchable leaderboard, and a page for each runner showing where they are, which regions they’ve completed and what to do next. A search on every runner page jumps straight to the next runner, and the leaderboard remembers its search when you come back.
  • Finisher certificates: a vector PDF with the route in its five region colours, a stamp for each region and a gold seal. The finisher’s name and date are written in their own browser when they download it; nothing is stored or sent.
  • A results archive: the 2024, 2025 and 2026 dashboards frozen exactly as they finished, so newer code can never show a finished race differently, and the main dashboard is free to become GVRAT 2027.

A Transcon runner page: the runner’s position on the course, regions completed, and a “Next step” telling them how many miles are left in Region 1

A Transcon runner page (my own). The "Next step" tells each runner what to do to keep moving.

The Transcon certificate of completion: the route across a map of the United States, a stamp for each region, and a gold seal for 3,361 miles

The Transcon finisher certificate, signed by Laz, Steve and me.

The rules were the hard part

The Transcon is built from years of separate registrations typed by thousands of people. Every rule was agreed in plain English, with a real runner as the example, before it became a function and a test.

  • One runner, many registrations. The same person can appear under a nickname one year and their full name the next, or with a typo in their date of birth. A series of fallbacks groups entries into one runner, while keeping apart twins who share everything but a first name.
  • Miles fill registered regions in route order. A medal can only ship for a region someone signed up for. Extra miles wait, and the runner’s page says which region to register for to use them.
  • Every logged mile counts. Activities from every entry go into one cumulative total, so switching between a GVRAT entry and a Transcon entry never loses a mile.
  • A fair cutoff. As on the race dashboard, a day counts only once it has ended in every time zone, and the page says so: “miles logged through November 6.”
  • Miles come from RunSignup and nothing else. The audit showed that the old logic counted a shipped medal as a finished region, and Steve sometimes mails medals a few miles early to save postage. Shipping records now stay private and only help decide what to send.

It runs itself

  • Every morning, GitHub Actions pulls registrations and activities from the RunSignup API, a Python pipeline groups runners, counts miles and applies the rules, and the public JSON is committed back.
  • Every afternoon, my Mac runs a full sweep as a backup, retrying on its own if RunSignup drops a connection.
  • History is frozen. Everything up to the end of September 2026 is saved once, so a re-run can never quietly change the past.
  • Tests gate every deploy, on both sites. Browser tests check every page at ten screen sizes, from a 320 px phone to a 2,560 px monitor, for broken links, console errors and clipped content. On the Transcon, every daily update also passes data checks before it goes live: the totals add up, every runner has a page, no region counts more than its distance, and no email address or private field is in the public files. If anything fails, the live site stays as it was. The first run of the new Transcon tests caught two layout bugs that had already shipped, both on small phones.
  • Board orders take care of themselves. Display boards are sold through a separate RunSignup race; each day the pipeline reads the new orders, matches them to runners, and flags only the ones it can’t match.

Emailing runners carefully

In November 2026 we began emailing every Transcon finisher, and every runner with miles waiting for a region they hadn’t registered for, each email written from that runner’s own numbers. Since then two emails go out every day after the update: a thank-you to each runner who registered for a region, telling them where they stand, and a congratulations when someone completes a region or the whole Transcon.

  • Three kinds of email, chosen from each runner’s page: finished with a board, finished without one, and miles waiting.
  • Sent from our own address through Google Workspace, with replies going to both race directors.
  • Small batches first, drawing from every group in turn, so we could read the first replies before sending the rest.
  • Never twice. Every send is recorded, and a batch stops if the count about to go out isn’t the count expected.
  • “Reply STOP” really works. Before every send the system reads the inbox for STOP and unsubscribe replies and removes those runners. If it can’t read the inbox, it sends nothing.
  • No old news, no promises we can’t keep. Turning the daily emails on noted everyone’s existing milestones without emailing them, so nobody got congratulated for last year. Medals ship in batches every month or two, so an email says a medal is earned and goes out with the next shipment, never that it’s on its way.

Proving the numbers

A results site is only worth anything if runners believe it, so before the first email I treated it as an audit.

  • Against the source: a fresh RunSignup export matched exactly, 4,116 of 4,116 registrations and 473,270 of 473,270 activities up to the frozen cutoff.
  • An independent recount, written separately from the pipeline, agreed on 1,648 of 1,649 runners. The one difference was a run logged on two entries, and it settled the rule that every logged run counts.
  • The honour rolls, corrected. Six runners who had finished every GVRAT were missing from the Hall of Fame because their email had changed. Runners sharing an email with a family member had been shown that person’s times. 93 runners split across two rows of the lifetime list are now one runner each, with their full miles, including five whose names had lost their accented letters in one year’s records.
  • Runners can correct us. Every results page ends with a short note asking runners to email us about a missing year or an old name. The first week brought name changes, a 2020 race run under a nickname, and a request to merge two entries, each fixed within a day.

Privacy by design

  • No personal details are published. Exports with emails, phones, addresses and birth dates never enter the public code; the site is built only from names, home state or country, and miles.
  • Fewer third parties. Fonts are self-hosted, and the Google map loads only when someone clicks it.
  • Opt-outs are stored as one-way hashes, not email addresses.

Working with an AI pair programmer

I built the rebuild with Claude Code as my pair. It never emailed a runner or changed hosting settings without my go-ahead, every design change was shown to me before it shipped, and private data stayed on my machine. My part was the judgement: what a runner needs to see, what a fair rule looks like, and when the numbers were right enough to put our names on.

How it started

We planned for 2,000. 19,600 showed up. During lockdown in India, I built a virtual-race system in under a week. Runners logged more than 12 million miles in the first four months. The work grew into years of running virtual events.

The decision

When demand exceeded the original plan, I made the case to keep entries open.

The build

Activity logging and processing, runner maps, certificates, and email communications. RunSignup handled registration and payments.

The people using it

I also answered participant questions about logging miles, correcting entries and finding their way around the platform. Clear written instructions helped people with different levels of technical confidence take the next step.

Beyond launch

We added challenges as runners finished early. The Circumpolar Race Around the World (CRAW) followed: a team relay along a 30,167-mile route, with nearly 55,000 registrations over four years. Read the CRAW case study.

Connected

Working on something similar? Let’s talk.