Part 1Installation

This part is for whoever stands the system up: one race director, once, at a desk with a network. Nobody working an aid station needs to read it.

Work through it in order. Each step is verifiable, and the verification is given, because the failure mode this system must never have is one that stays hidden until a tablet is at mile 45 with no signal.

#1.1What the system is made of

Five things run, and they are all the same event log seen from different places.

Two facts about this shape are worth holding on to, because most of the procedures below only make sense in their light.

Every client holds a real database. Not a cache — a local SQLite database with the race in it. A tablet that loses signal keeps working, keeps recording, and sends its work when it can. This is why the install order below puts the backend first: a client cannot be meaningfully tested until there is something for it to replicate.

What a device may see is decided by the server, not the app. A station tablet does not hide a runner’s phone number; it never receives it. That boundary lives in powersync/sync-rules.yaml, and §2.7 covers how to verify it rather than assume it.

#1.2Before you start

You need, in this order:

1. Node.js and npm, on the machine doing the install. The repo is an npm workspace; everything below is an npm script.
2. A Supabase account and a project for the environment you are building. Free tier is sufficient for a race.
3. A PowerSync account and an instance pointed at that Supabase project. Free tier is sufficient.
4. A Cloudflare account, for hosting the three web apps.
5. Android tablets, if you are using them, with developer mode enabled so builds can be installed over USB or wireless debugging.

#1.3Getting the code

git clone <your fork of the repository>
cd RaceTrak-IMTUF
npm run bootstrap

npm run bootstrap installs dependencies for every workspace at once. Do not run npm install inside an individual app; the workspaces share a single lockfile.

Confirm the domain logic is sound before going further:

npm run test
npm run lint

The test suite covers the event-log folds — the code that answers “where is bib 147” — and runs in seconds with no backend. If it fails, stop; nothing downstream will behave.

#1.4The backend

docs/backend-setup.md is the authority on this and goes deeper than a manual should. The shape of it:

1. Create the Supabase project and record its reference id and database password in infra/env/<env>.env. Start from infra/env/example.env; the real files are gitignored and never committed.
2. Apply the schema. npm run supabase:migrate dev runs every migration in supabase/migrations/ in order. This creates the event table, the row-level security policies, and the append-only triggers.
3. Deploy the pairing function. npm run supabase:functions dev publishes redeem-pairing-code, which is how every client — tablet, console and portal — turns a code into a session. Nothing can pair until this exists.
4. Enable logical replication on the Postgres instance and create the read-only replication role PowerSync will connect as.
5. Point PowerSync at it, then deploy the sync rules with npm run powersync:deploy dev.

Current schema state:

Generated from the source of record. Do not edit by hand.

16 migrations, through 0016_note_events.sql.

#1.4.1Verifying the backend

Do not take the console’s word for it. Two checks, both cheap:

• Replication is live. The PowerSync instance should report a connected replication slot with lag at or near zero.
• The append-only rule holds. Attempt an UPDATE and a DELETE against events as a privileged user. Both must be refused by trigger. If either succeeds, the migrations did not all apply.

#1.5The web clients

Three separate apps, three separate Cloudflare Pages projects per environment. They are separate on purpose: the portal writes directly to Postgres and is used at a desk, while the console replicates through PowerSync and keeps working when the uplink does not.

npm run build:web dev          # command console
npm run build:portal dev       # portal
npm run build:fieldweb dev     # field client in a browser

npm run deploy:web dev
npm run deploy:portal dev
npm run deploy:fieldweb dev

Every deploy targets the project’s production branch, so each app keeps one stable hostname that does not change when you deploy. Cloudflare also mints a per-deployment URL with a hash in front of it — those are build artifacts, not addresses.

#1.6The tablets

The field app is React Native under Expo. The android/ and ios/ directories are generated by expo prebuild and are not committed — never edit them by hand, because the next prebuild discards the change. Anything that must reach the native project goes through app.json or a config plugin.

RACETRAK_BUILD_VARIANT=release npm run build:android dev
adb install -r build/android/dev/app-release.apk

#1.7Verifying the whole chain

The install is not finished when things are deployed. It is finished when one tablet has carried a record all the way to Postgres. Do this once, deliberately:

1. Install a release build on a tablet that has never been paired.
2. In Settings → Race pairing, enter a station code from the portal.
3. Confirm the tablet syncs down: the roster appears and the station name is shown in the header.
4. Record one arrival.
5. Query the events table in Postgres and find that row, carrying the tablet’s own device id.

That path — code, function, session, sync rules, local database, screen, upload queue, Postgres — is the system. If it completes, the install is good.

#1.8Commands, in full

Every script takes an environment (dev, staging, prod) and prompts before touching production.

Generated from the source of record. Do not edit by hand.

Part 2Configuration Management

This part is for the race director and anyone helping set a race up. It covers what you configure, where each setting lives, and which settings are safety boundaries rather than preferences.

The dividing line worth learning first: the portal is where a race is set up, the console is where it is run. The portal writes straight to Postgres at a desk with a network. The console replicates through PowerSync and keeps working when the uplink does not. They share every importer and every calculation, so they cannot disagree about what a spreadsheet row means or where a runner is.

#2.1Environments

Three environments, separated by project rather than by branch: a separate Supabase project, PowerSync instance and set of Cloudflare Pages projects for each. That separation is what gives each environment a stable hostname and makes it impossible to point a production tablet at development data by accident.

Configuration lives in infra/env/<env>.env. Only example.env is committed — the real files hold credentials and are gitignored. Copy the example, fill it in, and keep the production file somewhere a second person can reach it.

#2.2Setting a race up

In the portal, in this order. Each step depends on the one before it.

1. Create an account and sign in.
2. Create the race — name and date.
3. Add the aid stations, in course order. Order matters: it is what makes “this runner never left the previous checkpoint” a question the app can ask.
4. Import the roster.
5. Add the crews — who is working which station.
6. Generate the station codes and distribute them.

All three imports — aid stations, crews and roster — accept a spreadsheet and offer a downloadable template, either blank or filled with the race’s current data. The filled template is the easier path for an edit: download, change, re-import.

#2.2.1Aid stations

Each station carries a name, its order on the course, and optionally a mile mark, opening hours, coordinates, and tags such as radio, water, medical or drop_bags. Cutoff times are set here too, and are what the field app counts down against.

#2.2.2The roster

Imported from CSV, with a mapping step: your file’s column headings are matched onto the fields the system needs — bib number, name, age, phone. Unpredictable headings are the norm and the mapper exists for exactly that; it can also combine two columns into one name.

#2.2.3Codes

Two kinds of code exist and they are not interchangeable.

One code per station, carrying whether that station is in, out or radio. The code says where the device is; the operator chooses what the device is doing (§2.8). Codes are generated in the portal — one button produces one code per station — and can be sent by SMS or email.

#2.3Roles, and what each one receives

This is the security model. It is enforced in the sync rules, which decide what each device ever receives, and again in row-level security in the database.

Generated from the source of record. Do not edit by hand.

The important property is negative and worth stating plainly: a station device does not receive runners’ phone numbers at all. They are not hidden in the interface — the rows are absent from the tablet’s database. There is nothing to leak, nothing to render by accident, and nothing recoverable by someone holding the device.

Emergency contacts are different, and are sent to station devices deliberately: the moment one is needed is at the checkpoint where somebody is on the ground, not at basecamp. Revealing one is a deliberate act that writes a permanent record of who looked (§3.6).

#2.3.1Verifying the boundary

Do not infer this from the configuration file. Confirm it:

1. Redeem a real station code and, with the session it returns, query the contacts table. It must come back empty.
2. With the same session, attempt to insert a runner. It must be refused.
3. On a paired tablet, confirm the local database holds zero contact rows.

If all three hold, both layers agree independently, which is the only form of this assurance worth having.

#2.4What a tablet is set to

Pairing decides the race and the station. Everything else is chosen on the device, in Settings, and can be changed mid-race.

#2.4.1Device role

Generated from the source of record. Do not edit by hand.

The device role sets what a single tap on the Record grid does. It is a default, not a restriction — every other action stays available behind a long press. An operator can override the direction for their shift, and that choice outranks the paired role.

#2.4.2Display: names are off by default

A station screen is a public surface — propped on a table, photographed, visible to anyone in the tent. Runner names are personal data, and the bib is what the job actually needs, so names are off unless someone turns them on.

#2.4.3Station lock

Station lock keeps a tablet on the recording screens so it cannot be wandered away from mid-shift. It is unlocked with a PIN, or with the race admin code.

#2.5Two tablets at one station

The IN and OUT operators are routinely a hundred feet or more apart — too far to share a tablet, and exactly the pair who most need each other’s data. When both are paired to the same station, they find each other over the station’s Wi-Fi and exchange events directly, with no internet involved.

The receiving device decides what it will accept: events for another race, unknown types, or events about nobody are refused regardless of what the sender claims.

#2.6Before a real race

Development settings are permissive by design. Every one of these must be changed before production carries real runners.

Part 3Operations

This part is for the people working a race: aid station operators, radio operators, and the director at basecamp. It assumes nothing about the rest of this manual.

Three things are true of this app, and they explain most of how it behaves.

It works with no signal. Everything you record is saved on the tablet the instant you record it. Sync happens in the background whenever there is connectivity. You never wait for the network, and losing it costs you nothing.

Nothing is ever deleted. Mistakes are fixed by recording a correction, so the log always shows both what was written and that it was put right. You cannot destroy a record by getting something wrong.

It will not stop you. Unknown bibs, duplicates, runners who appear out of order — all of these are normal at an aid station. The app tells you what it noticed and lets you decide. It never blocks a record.

#3.1Starting your shift

1. Check the tablet is paired. The station name appears at the top of the screen. If it says the device needs pairing, get the station code from the race director and enter it in Settings → Race pairing.
2. Set your name. Tap Set operator at the top, or go to Settings → Operator. This is how a record is attributed to you; it is not a login.
3. Check the sync status. Also at the top: Synced, Syncing… or Offline. Offline is not a problem — it is the expected state at most stations. It means what you record is waiting on the tablet, which is safe.
4. Check what the tablet is set to do. Settings → This device is decides what a single tap records. Make sure it matches the job you are doing.

#3.2The screens

Generated from the source of record. Do not edit by hand.

Whatever you type on the Keypad survives switching tabs and coming back. An operator moving between IN and OUT halfway through a bib number does not lose the digits they had already entered.

#3.3Recording arrivals and departures

Two ways, and they are for different moments.

#3.3.1The Record grid — the fast way

A square for every bib. One tap records the direction the tablet is set to. That is the whole interaction, and it is what you will use for hundreds of runners.

• Tap a square to record the default direction.
• Long press a square for everything else — corrections, notes, DNF, the runner’s history.
• Switch between Present and All to narrow the grid to runners currently at your station.
• Tap = IN / Tap = OUT at the top shows what a tap will do, and can be changed for your shift.

#3.3.2The Keypad — when the grid is too long

Type a bib. The runner’s name appears as confirmation. Then Record IN, Record OUT, or Other for anything else.

Recording OUT for a runner who was never recorded IN will record both, so a runner passing straight through is one action rather than two.

#3.4What the app tells you as you type

As you enter a bib, the app assesses it and tells you what it noticed. None of these stop you.

#3.5Radio: calling in to Net Control

The Radio screen shows movements that have not yet been passed to Net Control. It is a queue: work from the top.

1. Read the queue. Oldest first, except that drops jump the queue — a DNF is the thing Net Control most needs to hear.
2. Select the bibs you are about to transmit. Several at once is normal — real traffic is “bibs 47, 112 and 203 through Aid 4”, not one at a time.
3. Call them in.
4. Mark them called in. They leave the queue.

Each bib appears as one line per occasion. If the same bib is recorded several times within a few minutes, those collapse into one line with a count — that is two operators confirming the same runner, not two passes.

#3.5.1When a bib comes back

A bib that genuinely appears a second time is flagged, because it is more often a correction than a second lap:

• Amber — your station has two times for this runner and has transmitted neither. Check which one is right before calling either in.
• Red — the earlier time has already gone to Net Control. The flag names the old time and when it was sent, so you can correct the record over the air rather than adding a second one.

#3.6Fixing mistakes

Long press a bib on the Record grid, or tap its row in the Log, or use Other on the Keypad. Every correction is recorded as a correction: the original stays visible in the history and is marked as superseded.

#3.6.1Correcting a time

Operators log in bursts and the tablet’s clock is not the runner’s clock. A time recorded a few minutes late is normal and worth correcting.

When more than one time could be the one you mean — an arrival, a departure, a radio call-in — the app asks which time is wrong rather than guessing. Pick the one you mean, then set the correct time.

#3.6.2Notes

A note is for the context that otherwise lives in somebody’s head until they go off shift: the bib was upside down and might be 52, the runner said their knee had gone, the time came off a radio call rather than the tablet.

A note changes nothing. It is safe to add at any moment, including in the middle of a correction, and the director sees it in the console alongside the record it explains.

#3.6.3Emergency contact

A runner’s emergency contact can be revealed on a station tablet. It is deliberately a two-step action, and it permanently records who looked and when. That record cannot be removed by anyone.

Use it when someone is on the ground and you need to reach their people. Do not use it out of curiosity.

#3.7Working with no signal

This is the normal state at most stations, and nothing about it needs managing.

• Everything you record is saved on the tablet immediately.
• The status at the top will read Offline. Records accumulate safely.
• When signal returns, they upload on their own. You do not have to do anything.
• If a second tablet is working your station on the same Wi-Fi, the two share records with each other even with no internet at all.

#3.8When something looks wrong

#3.9For the race director on race day

The command console shows the whole race at once, and keeps working from its own local copy if basecamp loses connectivity.

• Whole race — every runner’s position across every station, sortable, with full history per runner. Tallies, cutoffs and unknown bibs. Every count is clickable through to the bibs behind it, and the field can be filtered to one station.
• Aid stations — the course, and the import wizard for changing it.
• Crews — station personnel.
• Roster — CSV import with the column mapper.

Two jobs only the console can do:

Naming unknown bibs. A bandit recorded at a station is saved against the bib number with no name. Matching them to a person is a console job, because a station is not permitted to assign identity.

Reading the contact details. The runner’s own phone number reaches the director and medical command and nowhere else.