Tabulous

Web tabulation for judged competitions. An admin sets up an activity, judges score entries from their own devices, and a public page shows every judge's score and the average, ranked live.

• Admin panel (/admin): create activities with a name, a score range (min to max), decimal places (whole numbers, or 1, 2 or 3 decimals; a pageant's sub-activities go to 2), whether scores show live (see Live scoring or a deliberation), judges with names and photos, and entries. Every photo (judges, entries and candidates, organizers) opens in a crop step first: drag it to choose what shows, zoom to make it bigger or smaller (or out to fit the whole photo), and it's saved as a small square. Each activity's tabs follow the event day: Session (the control desk), Judges (the panel, each judge's code and QR code, and approving their devices; the panel can be changed there until the session starts, including which judge chairs it: Make chair hands it to another judge), and LED wall for running the show; Entries and Settings (name, organizer, delete) for setting it up, where test sites add Test site tools (reset scores, and deleting the activity even mid-session). The live site doesn't have them, and nor do Vercel previews unless you turn them on (see Deploying to Vercel). Once its session has ended, an activity can be archived from the list of activities or its ended Session tab, when no more deliberating is needed: it moves to Archived activities (below the list) and from then on can't be reopened, deliberated again or changed, nor taken out of the archive; every judge's device is signed out and their codes stop working, the private tally closes, and the live results page closes: its link no longer works. From then on it can only be opened read-only to download its results, score sheets and the judges' notes, or deleted. Pageant mode is offered on test sites (locally, in CI and on a testing preview); the live site shows it as coming soon. On the Session tab you can hide or show ranks on the public page, and download the official results once every judge has scored every entry, from one Export menu: the results and the judges' score sheets as PDFs, the results and every judge's scores as CSV, and the judges' notes. A CSV carries the sheet's report ID and the SHA-256 fingerprint of its rows, and Check a CSV on the Settings tab says whether a copy is unchanged and matches the scores (a CSV is plain text, so it can't be locked; this is how an edited one is caught). Cells a spreadsheet would run as formulas are written as text. The PDF carries a report ID that changes if any score changes, marks each judge's sign-off (Sgd.), or their drawn signature after a deliberation, and prints the organizer's photo and the activity's signatories (for example the Board of Tabulators) with designations, set on its Settings tab. Next to it, Download judges' score sheets gives a second PDF with one sheet per judge: every entry in running order with that judge's score (and, with criteria scoring, their points for each criterion), signed by that judge and the signatories, under the same report ID. When judges wrote notes, Download judges' notes gives them as a third PDF, apart from the results. An archived activity's page has no live results link, QR code or LED wall: their pages are gone.
• Accounts: the super admin (the developer, using ADMIN_PASSWORD) creates, edits and deletes organizer accounts with an email, password, organizer name and photo. Organizer passwords need at least 8 characters, a number and a special character; the form ticks the rules off as they're typed. Organizers sign in with their email and see only their own activities; their name and photo show in the admin header, and their photo, as their logo, heads their activities' live results. An organizer can change the password they were given from their Profile (their current password first); their other devices are signed out. The super admin sees every activity and can hand one to an organizer from its Settings tab; organizers' activities are listed live ones first, then the newest 50 at a time. Deleting an organizer keeps their activities for the super admin.
• Judge portal (/judge): a judge enters their six-character code, or scans their QR code (which fills the code in, so they just tap Start judging), to sign that device in. The link itself signs nothing in: a messaging app previewing it, or a QR scanner checking it, would otherwise ask the organizer to approve a device that isn't the judge's. The device shows a pairing code and waits until the organizer approves it on the Judges tab, or from that judge's tile on the Session tab; only one approved device per judge can score, so a stray device that scanned the QR can't. Their screen then waits until the organizer starts the session, then shows the entry the organizer picks. They type the score on a large keypad and submit it, then wait for the next entry. Before a score goes in, the confirmation lays out each criterion's points to check, and after submitting the judge has 5 seconds to undo it; a score confirmed just before the organizer moves on still counts. With live scoring, that's final. In an event without live scoring (and in a pageant), a judge who entered a wrong score can ask to correct it while the entry is on screen (or any entry during the deliberation), with a reason: every other judge on their panel gets a pop-up they can't close until they vote (it waits while they're typing or undoing their own score), showing the reason (a pageant's also shows the score and the new one; an event's keeps the scores private), and the score changes only if every one of them agrees (one disagreeing keeps it). A judge alone on their panel asks the organizer instead, who approves or turns it down on the desk. The desk lists every correction and how the vote stands; the results PDFs wait while one is open, then list the corrections that changed a score. Once a score is in, its card lists the points for each criterion, and on a phone the count in the header opens the judge's scores so far (wider screens list them beside the keypad). Judges can keep a note on each entry: under the entry's name on a phone, or in a column beside the keypad from 1280px wide, which can pop out into a window they drag anywhere. Only that judge and the organizer read the notes: the organizer downloads them from the Session tab as a PDF of their own, a page per judge under the organizer's logo (the score sheets don't print them).
• Entry details (events): up to three details about each entry besides its name, such as a school, a division or a region, named when the event is created or on the Entries tab. They're typed after each name on its line, separated by |, or pasted from a spreadsheet, and edited beside each entry until judging ends. Only the organizer sees them: on the Entries tab, and as columns in the results PDF and CSV. Judges and the public pages never get them.
• Judges at their own pace (events without live scoring): an option at creation and in Settings until the session starts, off by default. Each judge then scores the entries in any order: their screen starts on the first entry they haven't scored, moves to the next after each score, and any entry in their list of scores opens to score it (or to see and correct the score given). The organizer shows no entries: the desk says how many scores are in, and the chair (or the organizer) starts the deliberation once every judge has scored every entry.
• Correction reasons from a list (events without live scoring): an option at creation and in Settings, off by default. A judge correcting their own score then picks why (a wrong number, a misread criterion, a missed part of the performance, mixed-up entries, reconsidering after every entry), or Other to type it. Every correction keeps its reason either way.
• Calls for help: a judge taps Assist me on their screen (it asks first), and the organizer is alerted on whatever page of the admin panel they're on: the page blurs behind a dialog listing every call still waiting, oldest first, a chime plays, and, once the organizer has turned alerts on, the browser shows a notification, so a call reaches another tab too. On my way answers a call, and the judge's screen says the organizer is on the way; a judge can take their call back. The panel hears of calls over realtime, keeping its connection while the tab is out of view, and checks every 15 seconds anyway.
• Privacy screen (judges' phones and tablets): while judging, turning the screen away from the judge (toward a neighbour, away from them, or face up on the table) hides it behind a blur until it's turned back, or the judge carries on in the new position. It reads the device's orientation on the device only. On for new activities; Settings turns it off. Where the browser asks before a page can read motion (iOS), a banner offers to turn it on.
• Scoring modes: simple (one score from a min to a max) or criteria (points for each criterion, adding up to 100, entered on the same keypad). Each criterion can have a lowest score in points, like a score sheet's "lowest possible score" (28 for a criterion worth 40); judges' keypads won't take less. Each can also have a guide for judges (guide questions or what to look for), shown on the judge's screen while they score that criterion; an event's guides can be edited in Settings until judging starts. Criteria totals show on the live results, LED wall and PDF as a percentage or scaled to 10.
• Judges' names: a first and a last name, in letters (any alphabet, with the spaces, hyphens, apostrophes and periods names carry, like "Ma. Dela Cruz" or "O'Neil"). Digits and other symbols are refused as they're typed.
• Pageant mode: choose Pageant when creating an activity, and a step-by-step setup asks for the candidates first (in running order, each with an optional photo for the LED wall and the judges' screens; a list of names pasted into one row fills it and the rows after, running numbers dropped, and Enter goes to the next name), then the judges, then the program. The pageant is created first and each candidate's photo is uploaded after it, one at a time, so a large field never goes over Vercel's 4.5 MB request limit; a draft keeps the photos too, as many as fit. A pageant has two segments, preliminary and pageant proper, and the admin sets the preliminary's share of the overall score (pageant proper gets the rest). Each segment has its own sub-activities (a closed-door interview and national costume; production number, swimsuit, evening wear, Q&A), each with its own scoring, simple or criteria. Shares are typed as percentages of the overall score, the way score sheets write them: with the preliminary at 40%, its sub-activities add up to 40 (an interview at 20, an advocacy at 10, an advocacy video at 10), and pageant proper's up to its first cut add up to the other 60. Scores start over after a cut: the sub-activities after it count from zero, their shares add up to 100% (a Q&A alone after the Top 5 is 100%, with no share to type), and they alone rank the next cut, so a cut can only count the sub-activities of its own stage. Adding or taking away a cut refits the shares to the new stages, keeping their proportions, and programs saved before are fitted the same way. Adding a sub-activity when a segment's share is used up splits it evenly to make room, and changing the preliminary's percentage rescales the shares that added up to the old one. A sub-activity can also be scored in parts, for one sub-activity with several deliverables (a closed-door interview with its Q&A, the advocacy and the advocacy video): each part has its own scoring, timer and share of the overall score, the sub-activity counts for its parts added up, and judges score each part on its own. The judges are one board for the whole pageant or separate boards for the preliminary and pageant proper, chosen on the setup's Judges step: each board has its own judges and its own chair (a chair can only move judging in their own board's segment), and each sub-activity waits for, counts, shows and is signed by its own board. Pageant proper needs at least three judges. On the Judges tab a judge other than a chair can still be moved between boards or set to judge both segments, and until the session starts a judge on a board's segments can take over as its chair (Make preliminary chair, Make pageant proper chair). After any pageant proper sub-activity the admin can add a cut (Top 10, Top 5): the form shows how many candidates are left before it and flags a size that leaves none out, it ranks the candidates by the sub-activities the admin ticks for it, and only the candidates who go through are judged after it. The last sub-activity ends with the (e.g. Top 3), whose order is the final placement. A cut counts each sub-activity as a candidate's average as a percentage of its maximum; when the first cut counts the preliminary with pageant proper sub-activities, the preliminary keeps its share. On the tab the organizer judges one sub-activity at a time, the whole preliminary before any of pageant proper (the desk won't start pageant proper while a preliminary score is still to come), reviews each cut, breaks any tie on the line (or, in the final cut, a tie for a placement) and confirms it. Candidates keep their number through every cut. A pageant can have for violations during the preliminary: turned on at setup (on the Preliminary step, or the Segments tab before the session) with the violations and their points listed, then given to a candidate from the desk's dialog, picking a listed violation or typing another reason and its points, until pageant proper starts. Deductions are points off the candidate's preliminary score, so a cut that counts the preliminary takes them off at its share (2 points, with the preliminary at 40%, take 0.8 off). Only the organizer sees them listed: the preliminary standings and cut PDFs show a Deductions column and each one with its reason, and their report IDs change with them; the live results and the LED wall, which show one sub-activity at a time, never list them. Every sub-activity (and each part, with a standings sheet for a sub-activity in parts), every cut, the final results and the preliminary standings have their own results PDF, and every sub-activity and part has its judges' score sheets too. The program can be changed on the tab until the session starts. From then on it's final: the tab is read-only, timers included, even after the session ends. During the show the desk can still give judges more time (, ).
• Drafts: an event or a pageant can be saved as a draft at any point while setting it up (Save draft), and continued or deleted from the Drafts list on the Activities page. Creating the activity clears its draft. Leaving with unsaved changes asks first: reloading or closing the tab gets the browser's prompt, and links, Sign out or switching between event and pageant get a dialog that can save a draft on the way out.
• Scoring timer (pageants): a sub-activity can give judges a set number of seconds to score each candidate, for example while they walk the runway. The timer starts when the candidate is shown. Judges' screens and the session desk show it in green while judges can score, yellow when it's about to close, and red once it has, with the time left; after that the server refuses scores until the organizer gives more time or restarts it from the desk.
• Judging session (Session tab): before judging, the desk shows which judges have an approved device. The organizer starts and ends judging and shows judges one entry at a time, watching who is still scoring and whether the desk's connection is live. Starting locks the judges and the running order; entries can still be added (until the judges start deliberating, when no one could score a new one) and renamed. Judges can only score the entry on screen while the session is live. Once the session ends, the desk shows the report ID and the results PDF.
• Live scoring or a deliberation: a new event starts without live scoring (Show scores live when creating it turns it on, or in Settings until the session starts): the audience sees each score the moment it's submitted, and a submitted score is final. Without live scoring, the audience sees the entries and a tick for each judge who has scored each one, but no scores (the server doesn't send them) until the judges have signed; the organizer's private tally (Session tab, Screens) shows every score so far, judge by judge and criterion by criterion, to tabulate by hand if something fails during judging, with where the show stands as on the live results (judging, the judges deliberating, ended): partial and unofficial until every judge has signed and the session has ended, official from then on, and judges can ask to correct a score. Once every judge has scored every entry, the desk (or the chair, from their own screen) offers Start deliberation in place of End session: each judge's screen then lists every entry with their own score, points per criterion, any correction and their notes, to review and correct; then they sign, by drawing their signature on a touchscreen (phone or tablet) or, on a screen without touch, by ticking "(Sgd.)". Signing waits while a correction is open, and a score corrected after anyone signed takes every signature back. The desk shows who has signed, and End session appears once they all have: from then on the results show on the live results page and the LED wall, and the results PDFs (refused until then) print each drawn signature above the judge's name. Reopening an ended session takes the signatures back; once the judges and the organizer have signed, it reopens only by deliberating again, with the password. Pageants always score live for now.
• Live results (/live/<id>): every judge's score and the average for each entry, updated in real time and made to be projected. Once the session has ended it says Ended, with the date and time, in place of Live; during a deliberation it says Judges deliberating, and an event without live scoring shows its scores only once the judges have signed. With ranks on, entries are sorted by average and the top 3 stand out; with ranks off, entries stay in running order. A pageant's page follows the sub-activity being judged, with only the candidates still in the running.
• Privacy policy and terms of service (/privacy, /terms): public pages, linked from the start page, both sign-in pages and the foot of the admin panel. The operator, contact address and effective date are in src/lib/legal.ts; the privacy policy describes what the app actually does (its cookies, logs, what the public pages show, what deleting removes), so change it together with that code.
• LED wall (/led/<id>): one entry's scores for the LED wall or video switcher, either as a slim lower third on chroma green (#00FF00) to key over the camera shot (one bar along the bottom with the entry, a tile per judge and the average, so the camera keeps the rest of the frame), or as a full-screen scoresheet. A pageant's wall shows the sub-activity being judged, with its name under the candidate's, and the candidate's photo from the setup beside it in both displays. Scores fade in as judges submit them, or, with Show scores only when every judge has scored, all at once when the last judge is in. With Keep judges anonymous, each judge's name and photo on the wall becomes a "?". The wall's Look is chosen there too: a font (standard, elegant serif, modern, condensed or classic capitals), a colour theme (navy, black and gold, crimson, emerald, royal purple, midnight teal, rose gold, sunset amber, berry, graphite, or a light pearl, champagne or sky, each keeping its text readable) and square, soft or rounded corners, for the green screen and the full screen alike. The green screen itself stays chroma green. The wall follows the entry being judged, fading each entry and score in; the admin picks the display in the LED wall tab.

Built with Next.js 16, Supabase (Postgres, Realtime and Storage) and Tailwind CSS 4.

Setup

1. Create a Supabase project at supabase.com.

2. Create the database. In the Supabase dashboard open SQL Editor, paste the contents of supabase/schema.sql and run it. It creates the tables, the score rules, the change feed live screens listen to over realtime, and the photo storage buckets. Running it again is safe.

   Databases set up before a feature existed need the migrations in supabase/migrations/. Once the release pipeline is set up (see Releasing), new ones reach both databases from GitHub when they're merged; to bring a database up to date by hand, run them in order: 003_led_wall.sql (also covers 002) for show ranks and the LED wall, then 004_organizer_accounts.sql for organizer accounts and the LED display settings, then 005_judging_session.sql for judging sessions, then 006_devices_criteria_signatories.sql for judge device approval, criteria scoring and PDF signatories, then 007_entry_photos_result_decimals.sql for entry photos and result decimals, then 008_judge_names_and_chair.sql for judges' first and last names and the chair, then 009_led_transition.sql (optional now: it added an LED wall animation choice that has since been removed), then 010_led_anonymous_judges.sql for keeping judges anonymous on the LED wall, then 011_pageant_mode.sql for pageant mode (segments, sub-activities, cuts and the scoring timer), then 012_pageant_parts_and_drafts.sql for sub-activities scored in parts and saved drafts, then 013_judge_panels.sql for separate boards of judges, each with its own chair (if you ran an earlier copy of 013, run it again: it's safe to repeat), then 014_led_look.sql for the LED wall's font, colour theme and corners, then 015_deductions_and_themes.sql for pageant deductions and the LED wall's newer colour themes, then 016_private_results.sql, which makes scores and the other results tables private (see How it works below), then 017_sign_in_limits.sql for limits on guessing admin passwords and judge codes (until it's run, sign-ins work without the limit), then for judges' notes (until it's run, judges' screens leave notes out), then for score corrections (until it's run, judges aren't offered them and scores stay final), then for when a session ended and archiving (until it's run, the live results say "Ended" without the time and activities can't be archived), then for live scoring on or off, the deliberation, judges' signatures and three decimal places, and two indexes for many activities at once (until it's run, every event scores live), then for admin sessions that can be ended (until it's run, sessions work as before; once it is, admins sign in again once), then , three indexes that keep deleting an entry or an activity, and the super admin's list of organizers' activities, quick however many scores and activities there are (best run between shows), then , the rule that a session with scores can't go back to not started, for databases that ran 021 before it was added there (it changes nothing on one that has it), then , for a judge correcting their own score in an event without live scoring, then for breaking ties in the deliberation and the organizer's signature that ends it, then for signatories set on each activity, which starts each one with its organizer's (until it's run, every activity prints its organizer's), then , so the database itself refuses a score once judging has ended, and a score a judge confirmed just before the organizer moved on still counts (until it's run, such a score is refused and the app alone checks the session), then , which makes the database finish what used to take the app several writes (deliberating again or reopening clears every signature in the same change; archiving signs every judge's device out in it) and keep rules the app followed on its own (the deliberation starts only with every score in, no entry is added during it, and a judge has one approved device at most). Until it's run, the app makes these changes itself, as before. Then , which has the database check that the session hasn't started and write the running order in one step (moving an entry, or shuffling an event's order), so a session starting at that moment can't begin on half a new order. Until it's run, the app checks and writes the order itself, as before. Then , which hands the chair of a board of judges from one judge to another in one step, and only before the session starts. Until it's run, the app hands it over itself. Then , for judges' calls for help (), judges seeing the overall ranking in the deliberation, and the privacy screen on judges' phones (on for activities created after it, off for those before). Until it's run, the app leaves all three out. Then , for entry details (up to three per event, such as a school or a division, seen only by the organizer on the Entries tab and in the results) and correction reasons from a list. Until it's run, the app leaves both out. Then , for judges scoring at their own pace. Until it's run, every event is judged an entry at a time. Each only adds tables and columns, so a deployed older version keeps working after you run it, except 016: an older version's screens then stop hearing realtime changes and check every few seconds instead, until this version is deployed.

A live database and a testing database

Use two Supabase projects, each set up with schema.sql: one for the live site, and one for testing (running locally, the web tests and Vercel previews). Rehearsals, test runs and previews then never touch a real event.

• .env.local has the testing project's values. npm run dev and npm run test:e2e use it.
• .env.production.local has the live project's values. npm run build and npm start use it (Next.js reads it ahead of .env.local in production mode), so a laptop running the event at the venue scores into the live database. Give it every variable: one missing there falls back to .env.local.
• The two use different SESSION_SECRETs, so a sign-in from testing never works on the live site.
• Run each new migration on the testing project first, then on the live one.
• Don't use vercel env pull to fill .env.local: Vercel's Development environment has none of these values (sensitive ones can't go there), so it would replace your testing settings with a file that has none of them.

Running an event

1. Create the activity in the admin panel. You land on the Judges tab. To draw an event's order of presentation at random, use Shuffle order on the Entries tab, as often as you like, before the session starts: starting it locks the order.
2. Give each judge their code, or have them scan their QR code. Judges can also open /judge and type the code. Each device shows a pairing code: approve the matching one on the Judges tab, or from the judge's tile on the Session tab.
3. Open the public results link on the venue screen, or share it with the audience.
4. In the Session tab, start the session, then show each entry in turn. When every judge has scored, show the next one. End the session after the last entry.
5. For the LED wall, open the LED wall link full screen on the computer that feeds the wall or video switcher, and key out the green. The wall shows the entry being judged on the Session tab; choose the display in the LED wall tab.
6. Use Reset scores after a rehearsal to start clean, from Settings > Test site tools. It also deletes the judges' notes, signs every judge's device out (judges sign in again with their codes, and you approve the new devices) and puts the session back to not started. Neither is on the live (production) site, nor in any other production build (a Vercel preview, or npm start on a laptop) unless TEST_TOOLS=on says it uses a testing database.
7. After the last entry, end the session. The Session tab then shows the report ID and Download results PDF.

Many activities at once (breakout sessions)

Fourteen activities live at once with three judges each (42 judges' devices, a desk and an LED wall per room) were load tested on the testing project: all their screens stayed connected and scores kept arriving, with room to spare, at many times the pace of a real show. Two things decide whether a long day holds up:

• The database's size. Supabase's smaller compute sizes run on burstable CPU: they take short bursts of load well, but after a long stretch of heavy load they slow right down (in testing, saving a score went from a fraction of a second to many seconds). For an event day with many activities, use at least the Pro plan and a compute size above the smallest, and watch CPU on the project's dashboard; compute can be raised for the day and lowered after.
• The audience's phones. They check for changes rather than holding realtime connections, so a crowd costs a small read every few seconds each (and each read is a line in Supabase's logs, which its plans now meter). Prefer projecting the live results in each room over hundreds of phones following them.

Running on a laptop over the venue Wi-Fi

Judges' phones and tablets must be on the same Wi-Fi as the laptop. For the event itself, use a production build; it is faster and more reliable than the dev server, and it uses the live database from .env.production.local (see A live database and a testing database):

npm run build
npm start -- -H 0.0.0.0

The admin panel works at http://localhost:3000/admin on the laptop. Judge links, QR codes and the results link automatically use the laptop's Wi-Fi address (for example http://192.168.1.16:3000) so other devices can open them. Set NEXT_PUBLIC_SITE_URL to pin a specific address.

npm run dev -- -H 0.0.0.0 also works for testing on phones; the dev server allows this laptop's network addresses.

With nginx in front, for a real event

On its own the app can't tell the devices on the Wi-Fi apart. Next.js doesn't give server actions the connection's address, so the limits on guessing judge codes and admin passwords count by the X-Real-IP and X-Forwarded-For headers, which any phone can send. deploy/nginx/tabulous.conf puts nginx in front: it replaces those headers with each device's real address, lets go of stalled connections, refuses oversized requests, and caps sign-in attempts per device (judge sign-in and admin sign-in only; scoring is never slowed). The app then listens on the laptop alone, so every device goes through nginx.

1. Install nginx: brew install nginx on a Mac, sudo apt install nginx on Ubuntu or Debian.

2. Include the config inside nginx's http block. On a Mac: ln -s "$PWD/deploy/nginx/tabulous.conf" "$(brew --prefix)/etc/nginx/servers/tabulous.conf". On Linux: sudo cp deploy/nginx/tabulous.conf /etc/nginx/conf.d/, and remove the package's welcome site (sudo rm /etc/nginx/sites-enabled/default), which would otherwise answer on port 80 instead. Check it with nginx -t.

3. Start the app on the laptop only, then nginx:

   npm run build
   npm start -- -H 127.0.0.1
   brew services start nginx   # Linux: sudo systemctl reload nginx
   

The admin panel is then at http://localhost/admin, and judge links, QR codes and the results link use the laptop's Wi-Fi address without a port (http://192.168.1.16). nginx listens on port 80: if it can't open it (another app has it, or the system wants it started with sudo nginx), change both listen lines in the config to another port, such as 8080, and open that port instead. It doesn't add HTTPS: phones only trust a certificate for a real domain, so on venue Wi-Fi sign-ins still travel unencrypted. For that, run the event on Vercel.

Deploying to Vercel

Import the repository in Vercel and add the same environment variables. Set NEXT_PUBLIC_SITE_URL to your production URL.

The server functions run in Seoul (icn1, set in vercel.json), the region of both Supabase projects: every page and action makes a few trips to the database in a row, and from Vercel's default region (Washington, D.C.) each one crosses the Pacific. If you move the database, move the functions with it.

Give the live project's values to the Production environment only, and the testing project's to Preview (pull requests and branches), with their own SESSION_SECRET and TEST_TOOLS=on. Previews hide the test site tools, which reset scores and delete activities, unless TEST_TOOLS=on: a preview given the live variables by mistake can't wipe a real event. Running locally (and in CI) always has them.

Releasing

Pull requests deploy to Vercel previews on the testing database; main deploys to production. Three things keep a release safe; each needs a one-time setting.

Only tested code reaches production. In GitHub, protect main (Settings > Rules > Rulesets, or Branches): require a pull request and the CI checks Lint, types and unit tests, Schema and migrations and Web tests. In Vercel, add the same checks as Deployment Checks (Project > Settings > Deployment Checks), so a production deployment goes live only once they've passed.

Migrations reach the databases from GitHub (.github/workflows/migrate.yml): merged into main, a new file in supabase/migrations/ is applied to the testing project, then to the live one once you approve it. Each project records what it has run, so nothing runs twice by accident. To set it up:

1. Create a Supabase access token (supabase.com > Account > Access Tokens) and add it to the repository's Actions secrets as SUPABASE_ACCESS_TOKEN.
2. Create two GitHub environments (Settings > Environments), testing and live. In each, add the variable SUPABASE_PROJECT_REF (the project's id, from its URL) and the secret SUPABASE_DB_PASSWORD (Project Settings > Database). On live, add yourself as a required reviewer: live migrations then wait for your approval.
3. Tell each project which migrations it has already run (it only records them once the pipeline runs them). For the live project, list the ones you've run there; as of 18 October it had run 002 to 023: npx supabase migration repair --status applied 002 003 004 005 006 007 008 009 010 011 012 013 014 015 016 017 018 019 020 021 022 023 --linked --project-ref <live ref>. The testing project is already recorded through 023. The pipeline runs everything after that (024 first), the next time a migration is merged or when you run the workflow by hand.

Writing a migration: the next number (024_what_it_does.sql), and the same change in supabase/schema.sql, which creates new databases. A migration only adds: never drop or rename anything the deployed version still uses, since the database is shared by the version before and the version after, and a rollback goes back to the version before. Remove it in a later migration, once no deployed version uses it. Make it safe to run twice (if not exists, create or replace). Never change a migration once it's merged: a database that has run it won't run it again, so the change would never reach it (the session rule added to 021 after the live project had run it is why 024 exists). Put the change in a new one. npm run check:migrations checks all of this against main, and CI runs it on every pull request.

Production changes between shows. A deploy reloads every screen that's open (a judge loses what they were typing), so don't let one go live mid-show. Either don't merge while a show is running, or turn off automatic promotion (Vercel > Settings > Environments > Production > Auto-assign Custom Production Domains): each production build then waits until you promote it. Skew Protection (Vercel Pro) lets screens open before a deploy carry on with the version they loaded. To undo a release, Instant Rollback switches back to the previous deployment; the migrations only add, so the version before keeps working on the database as it is.

Node.js is pinned in package.json (engines), which Vercel and CI both use.

How it works

• All writes go through Next.js Server Actions using the Supabase secret key. The browser only gets the publishable key, which can read nothing but activity_changes: one row per activity saying when it last changed, kept up to date by database triggers. Scores, judges, entries, activities and programs are private, so hidden ranks and anonymous judges can't be read around the app.
• Judge access codes live in a separate table with no public access.
• Database triggers check every score against the activity's range and decimal places, and reject any change to a submitted score except through an approved correction (see Judge portal above), which the database applies in the same transaction that settles it. A score that changes after judges signed takes every signature back, only an event without live scoring can deliberate, and its session can't end from the deliberation until every judge has signed (migration 021).
• Sessions are signed, http-only cookies (SESSION_SECRET). Admin sessions last 12 hours and judge sessions 3 days. To change the secret without signing everyone out (mid-event, say), set SESSION_SECRET_PREVIOUS to the old value and SESSION_SECRET to the new one, and redeploy: sessions signed with either keep working, and every new one is signed with the new secret. Remove SESSION_SECRET_PREVIOUS after 3 days, once the last session it signed has run out. Changing SESSION_SECRET alone signs everyone out at once, which is what you want if it leaked. Organizer passwords are hashed with scrypt; changing one signs that organizer out on other devices, and deleting an account ends its sessions. Changing ADMIN_PASSWORD signs the super admin out everywhere.
• Each admin sign-in is also a row in admin_sessions, named by its cookie, and checked on every request (alongside the account, so it adds no wait). Signing out deletes the row, so the session ends wherever its cookie is, a copy included; an admin's profile lists the browsers signed in to their account and signs any of them out. Every app instance checks the same table and the same signature, so any instance can serve any request.
• Guessing is limited. Within 15 minutes, 10 wrong admin passwords from one network address, 50 for one account, or 25 wrong judge codes from one address (judges at a venue often share one) refuse further tries from it until the oldest fall out of the window. Failures are kept in a server-only table and cleared after a day. On Vercel the address comes from Vercel's own headers; a server started with next start trusts the browser's, so there only the per-account limit holds.
• A judge link opened on a device already approved for another judge asks before switching, since switching signs it out and needs the organizer's approval again.
• Photos are checked by their contents, not the type the browser declares: only JPEG, PNG and WebP are stored, with the type their bytes show.

Observability

The server writes one JSON object per line to its log (on Vercel: the project's Logs), so lines can be searched by field, counted, and turned into percentiles. Nothing secret goes in: no passwords, judge codes, cookies or query strings.

event	When	Fields worth watching
action	Every server action and export, once answered	action, outcome (ok, refused with the person's error, or failed when it threw), ms in all, dbMs of it waiting on the database over dbCalls calls (dbErrors failed), request (Vercel's request id)
db_error	A database or Storage call that failed (not a duplicate a retry expects)	path (the table or file), status, the database's code and error
slow_db	A single database call over 500 ms	path, ms
request_error	A page, route or action that threw	route, kind, digest (the reference the admin's error screen shows)
client_problem	A screen reporting what went wrong on it	kind (score_unreachable, action_unreachable, out_of_date, realtime_down, screen_error), where, device
runtime	Each minute, per server, in production	loopP99Ms (how late its timers run: a server too busy to answer promptly), rssMb, heapMb
score_not_saved and others	A write that failed, named for what it was	code, error

• Latency: p95 and p99 of ms per action (not the average: a few slow saves are what judges notice), with dbMs saying how much of it was the database.
• Errors: failed actions, db_errors and client_problems per action or screen. A refused action is the app saying no (a validation message), unless dbErrors is above 0.
• Saturation: runtime.loopP99Ms and memory per server; database CPU and connections in the Supabase dashboard; Realtime's own share of database time in the show report below.
• Vercel keeps runtime logs only for a limited time, shorter on the free plan. To keep a show's worth and chart percentiles, add a log drain to a log service.
• The database over one show: supabase/show-report.sql resets the database's query statistics before a show and lists afterwards where its time went: each query's calls, mean, spread and worst case.

Scripts

Command	What it does
npm run dev	Start the dev server
npm run build	Production build
npm test	Unit tests for keypad input, score validation, ranking and progress
npm run test:e2e	Web tests in a real browser (Playwright)
npm run lint	ESLint
npm run typecheck	TypeScript
npm run check:migrations	schema.sql and the migrations agree (against origin/main, or the ref given)

Tests and CI

GitHub Actions runs on every pull request and every push to main (.github/workflows/ci.yml):

• Lint, types and unit tests: npm run lint, npm run typecheck, npm test.
• Schema and migrations: npm run check:migrations: a database set up from main's schema.sql and brought up to date by this branch's new migrations matches one created from this branch's schema.sql, and each new migration is safe to run twice.
• Web tests: starts a throwaway local Supabase on the runner, loads supabase/schema.sql, builds the app and runs the Playwright tests in e2e/ against it. They walk through a whole event: creating an activity with a judge photo, judges scoring on a phone and a tablet, the live board updating in real time, hiding ranks, the results PDF and the judges' score sheets, the LED wall, and resetting and deleting from Settings on a test site. A second run takes a pageant from its step-by-step setup (candidates reordered and given a photo that shows on the LED wall in both displays, separate boards of judges for the preliminary and pageant proper, and deductions for violations listed) to the final results: a cut with a tie on the line that the organizer breaks, a scoring timer that closes and is reopened, and each sub-activity's, cut's and segment's results PDF. They also check sign-in guards and scan key pages for WCAG 2.1 AA issues. The HTML report is attached to each run.

To run the web tests locally, start the app with npm run dev and run E2E_PORT=3000 npm run test:e2e. They use your .env.local project, create an activity named E2E … and delete it at the end.

Fonts

The UI uses Avenir Next, which is built into Apple devices. Other devices fall back to Nunito Sans from Google Fonts. If you have an Avenir web-font license, add the files with next/font/local in src/app/layout.tsx.