Apolloon race operations
Paid client project, 2025–2026
- Role
- Sole developer, built it end to end
- Stack
- React, TypeScript, Express, tRPC, SQLite, Electron
- Runtime
- Three Electron laptops, wired LAN, browser screens
I built the software for a 24-hour relay race. It runs on three laptops on the event's wired network, with no cloud service. Each laptop keeps the whole race in SQLite, and the three agree on every change by majority vote, so a laptop can die without losing a confirmed lap.
Purpose
Running a race without the cloud
For 24 hours, the software registers runners, runs the queue and the warm-up, records laps, fixes mistakes, shows the live race on TVs, and exports results to Excel and CSV. The timer records a lap by typing the runner's number or pressing Space. The people at the tables aren't technical, so a failing laptop must never need a decision from them, and no two laptops may ever disagree about the queue or the laps.
- Three laptopsTiming, the queue desk, and the warm-up post. Each one holds the full database, and changes can be made from any of their screens.
- Browser screensTVs and extra laptops open a laptop's address in a browser and store nothing. When their laptop dies, they reopen the same page on another laptop within 2.5 to 8 seconds.
- Live updatesScreens get every change through a tRPC subscription over WebSocket.
Runtime
A desktop app with its own backend
↓ UDP broadcast discovery + Raft over WebSocket ↓
Consistency
What a single write goes through
A change made on any screen goes to the leader. The leader writes the change and its log entry in one SQLite transaction, sends the entry to the other laptops at once, and confirms it to the screen once a majority has stored it. Nothing ever needs merging, because only one laptop decides the order.
- Exactly-once retriesEvery change carries a request ID. If the leader dies while a change is on its way, the next leader applies it once.
- No lost lapsOnly a laptop that holds every confirmed change can win an election, so a takeover never loses confirmed data.
- No two leadersA leader that can't reach a majority for 1.5 seconds steps down. A laptop behind a broken cable stops saving instead of recording laps the others never see.
- Catching upA laptop that comes back catches up from the leader. If it holds changes the group never confirmed, it backs up its database first and then installs a full copy from the leader.
Failover
Automatic, by majority vote
The leader sends a heartbeat every 150 ms. When a laptop hears nothing for 1.5 to 3 seconds, it checks whether an election could succeed and then asks the others for their votes. With two of the three laptops up, everything keeps working. With one left, nothing is saved until a second one is back, unless someone confirms that the others are gone for good. That's why the design needs three laptops: with two, losing either one stops saving.
- Shared clockThe laptops have no internet time, so each one measures its offset to the leader's clock every two seconds.
- Replication is not backupEvery laptop takes a SQLite backup every five minutes and checks it with
quick_checkandforeign_key_check. It keeps the last 48 scheduled backups, and a restore covers the whole group. - Version checksLaptops only link when their app version and database schema match.
- Cross-platform buildsThe same self-contained Electron app is packaged for Linux, Windows, and macOS.
Testing
Tested on the real laptops
The repository has about 45 test files, including end-to-end tests of a linked group and a simulation of the Raft algorithm. A failover benchmark measures how long screens take to move to another laptop. A rehearsal script runs on the actual event laptops: it kills the app, cuts cables with firewall rules, and freezes laptops.
Ownership
What I built
This is paid client work, so the code isn't public. I wrote all of it, from October 2025 on:
- The Electron runtime, the typed API between browser and server, and the SQLite data model.
- The Raft group: elections, replication, catching up, automatic linking, discovery on the LAN, and browsers that move between laptops.
- The operator screens for registration, the queue and warm-up, timing, lap corrections, the live race, and exports.
- The tests, the Raft simulation, the failover benchmark, and the hardware rehearsal.