How it's built

A task, as the playbook stores it

Nothing about a role is written into the code. This is the 1st call as it lives in the playbook: a template for the label, when it happens relative to the event, who does it, who else may, who sees it, and how it gets done. Every task around every track event is one of these.

# meet_planner/defaults.py
{"id": "call1",
 "label": "{event} 1st call",
 "notes": "Athletes to the clerking table",
 "ann_notes": "1st Call, {event_call}",
 "when": {"anchor": "call1"},
 "owner": "announcer",
 "also_by": ["admin"],
 "watchers": ["*"],
 "mode": "tick",
 "core": True}

What it becomes on meet day

For the Girls 400m, 4 heats, expected at 9:44, with the playbook's calls at 30, 15 and 10 minutes before:

Add a role to the playbook, or a task around every race, and this table, every role's page, the printed guide and the How it Works drawing all change. There is no second place to update.

Every task has exactly one owner, the role that does it. Other roles can watch it: the calls are shown to everyone, so the clerk's phone says "1st call made" the moment the announcer checks it off. A task gets done in one of three ways:

• Tick. Someone checks it off. The announcer's calls, the script, the hype song.
• Fact. It's done when something happens. "All heats sent?" is done when the last heat is sent; "begins" is done when the race is started.
• Tick or fact. Either. "Putting heats together" can be checked off, or it counts as done when the first heat goes to the start.

Starting a race implies its calls, forming and sending, and closes everything about the races before it. That's why nobody checks off the same thing twice, and why a late check-off doesn't leave a phantom "not done" on someone's list.

When a role isn't at a meet (no announcer at a regular meet, no clerk helper today), each of its tasks follows the playbook's rule for that role: pass to another role, switch off, or ask. A task nobody owns is flagged on Setup with one-tap fixes. It can't quietly disappear.

# meet_planner/roles.py
def resolve_owner(owner, absent, roles, present):
    """Who does an action at this meet: (role, status)."""
    if owner in present:
        return owner, "ok"
    if absent == "off":
        return None, "off"
    seen = {owner}
    rule = roles[owner].get("fallback")
    while rule not in (None, "ask", "off") and rule not in seen:
        if rule in present:
            return rule, "inherited"
        seen.add(rule)
        rule = roles[rule].get("fallback")
    return None, "off" if rule == "off" else "unowned"

Each meet has a version number that changes whenever anything about it is saved. A page asks for it every 15 seconds and reloads if it changed, unless someone is typing. The heat board asks every 4 seconds and redraws in place, so two clerks on two phones see each other's taps almost immediately.

Websockets would be faster. They would also mean a long-lived connection per phone, a different server setup, and something new to go wrong on a laptop on an infield. Fifty phones polling every 15 seconds is about four requests a second, each answering with a dozen bytes. The simplest thing works, and it keeps working when a phone drops off the Wi-Fi and comes back.

Writes go through one method. store.update re-reads the meet, applies one change, and saves, all under a lock, so two people tapping in the same second both get saved. The meet is one JSON file; on Windows a file can't be replaced while it's being read, so reads wait for writes too.

// static/app.js
const check = async () => {
  try {
    const v = (await (await fetch(el.dataset.versionUrl,
                       { cache: "no-store" })).json()).v;
    if (version === null) version = v;
    else if (v !== version && !typing) location.reload();
  } catch { /* offline: try again next time */ }
};
setInterval(check, 15000);

# meet_planner/store.py
def update(self, meet_id, change):
    """Read the meet, apply change(meet), save it, all under one lock."""
    with self._lock:
        meet = self.load(meet_id)
        result = change(meet)
        self.save(meet)
        return result

105 automated tests, from parsing a heat sheet to which role can open which page, two clerks ticking the same heat, and the schedule after a late start and a delay. The documentation is tested too, because a guide that names a page that no longer exists is a bug a volunteer will find on meet day:

# tests/test_meet_planner.py
def test_every_help_page_renders_for_every_role(client): ...
def test_guide_links_anchors_and_screenshots_all_resolve(): ...
def test_guide_names_only_pages_and_roles_that_exist(): ...
def test_role_guides_and_staffing_are_filled_in_for_the_meet(client): ...

Every screenshot on this site and in the guide is taken by a script from two made-up meets, at a fixed moment in a demo morning. That's possible because the app never asks the computer what time it is directly: one module answers "now", and an environment variable can set it to any date and time, still ticking.

# meet_planner/clock.py
"""Set FIRST_CALL_CLOCK to a date and time ("2027-05-29 09:05")
before starting the app and every page behaves as if it were that
moment, with the clock still ticking from there."""

def now() -> datetime:
    offset = _offset()
    return datetime.now() + offset if offset is not None else datetime.now()

The same seam is what will let a hosted server run in UTC while each meet keeps its local time.