Console and scorer apps

What this part does

This part is everything a person touches. It decides how a screen shows data, how a change is sent and confirmed, and how the screen stays fast and safe under pressure. A wrong answer here means an operator loses a change, trusts old data, or slows down when speed matters most.

The design section answered seven questions:

Who uses which screen

How it works

The console and the desks are separate web apps. The admin panel draws each one in an iframe and answers its messages. This is how one change travels today, step by step:

1. The panel opens the app. It asks omnium for a session (GET /apps/session), draws the iframe, and waits for the app to say ready (frontend-admin/src/components/bridge/AppFrame.tsx:286-293).
2. The handshake. The app posts ready; the panel answers hello with the session: the event or fixture, the person's name, canWrite, and the read models and commands this app may use (packages-ts/omnium-bridge/src/host.ts:260-268). The app accepts messages only from the origins its build trusts (app.ts:90-116).
3. The screen reads and watches. A screen asks for a named read model, such as games.medal_table or results.fixture. Most reads are watched: the panel re-reads them when data changes and pushes the new value (omnium-console/src/lib/bridge.ts:148-212).
4. The person makes a change. The screen calls send(code, input). The bridge wraps it as a command message with a key and posts it to the panel (app.ts:323-337).
5. The panel sends it to omnium. It checks canWrite, checks the command is offered, then makes POST /workflows/{workflow}/subjects/{kind}/{ref}/commands with the person's sign-in (host.ts:307-321, http.ts:211-213).
6. omnium runs the command. The workflow engine locks the subject, checks the key, runs the rules, and saves. Every accepted command writes a row to timeline_item and one to domain_event in the same transaction. The page Commands and the workflow engine explains this road.
7. The answer comes back. Accepted, duplicate, or refused with the rule's own sentence. The panel posts it to the app, and the screen shows a toast.
8. Other screens catch up. The panel listens to the change stream. When a change lands, it waits 250 ms for a burst to settle, re-reads the watches the change touched, and pushes only values that changed (host.ts:188-235).

The agreed design keeps this road and adds three things in the browser. Changes go through a shared outbox. They show at once with a field state. A field registry protects typing from live pushes. The rest of this page explains each one.

Screens, and the command behind each action

Every button or field that changes data sends exactly one named command. Nothing else writes those records. This table maps the console's actions to commands, checked in omnium-console/src/lib/api.ts on 7 Oct.

The desks send their sport's own commands, for example cricket.delivery, boxing.judge_score, chess.move and swimming.split, plus core.correct and core.void (checked in boxing-scoring-ui/src on 7 Oct).

The console and the desks, side by side

The user asked how things will work "at both places". This is the difference today, and what the design makes the same.

A worked example

Low-level design

The bridge messages (built)

The bridge is one protocol, version 1, with fixed message shapes. Every message carries omnium: "bridge", so other messages on the page are ignored.

// packages-ts/omnium-bridge/src/protocol.ts:124-146 (trimmed)
export type AppMessage =
  | { type: "ready"; protocol: number; app: string; version: string }
  | { type: "read"; id: string; name: string; params: Params; subject?: SubjectRef }
  | { type: "watch"; id: string; name: string; params: Params; subject?: SubjectRef }
  | { type: "unwatch"; id: string; watchId: string }
  | { type: "command"; id: string; code: string; input: Record<string, unknown>;
      key: string; subject?: SubjectRef; dryRun?: boolean }
  | { type: "state"; id: string; op: "get" | "put"; scope: string; /* ... */ }
  | { type: "open"; id: string; target: OpenTarget; ref: string };

The app sends these to the panel. id matches a request to its answer. key is the command's idempotency key: a random id that lets the server spot the same command sent twice. subject lets an event's console address one of that event's fixtures.

// packages-ts/omnium-bridge/src/protocol.ts:93-109 (trimmed)
export interface CommandResult<T = Record<string, unknown>> {
  accepted: boolean;
  duplicate: boolean;
  seq: number | null;
  message: string | null;   // a rule's own sentence when it said no
  refusal: string | null;
  reason?: string | null;   // a fixed word, like likely_duplicate
  touches?: string[] | null; // what it changed, for live re-reads
  value: T | null;
  // counts, notes, dryRun, fixtureStatus
}

This is what every screen gets back. Today there are three outcomes: accepted, duplicate, refused. The agreed conflict and try_again answers come from Section 4 and are not in this type yet.

How a screen sends a change today (built)

A change passes through four layers. Each is short.

// omnium-console/src/lib/bridge.ts:113-127
export async function send<T = Record<string, unknown>>(
  code: string, input: Record<string, unknown>, subject?: SubjectRef,
): Promise<CommandResult<T>> {
  const sent: Record<string, unknown> = {};
  for (const [key, value] of Object.entries(input)) {
    if (value !== undefined) sent[key] = value;
  }
  const result = await bridge().command<T>(code, sent, subject ? { subject } : {});
  if (!result.accepted) {
    throw new Refused(result.message ?? "omnium did not take that change.", result.reason ?? null);
  }
  return result;
}

The console's one send(). It drops empty fields and turns a refusal into an error that carries the rule's sentence. Note what it does not pass: a key. So the bridge makes one.

// packages-ts/omnium-bridge/src/app.ts:323-337
async command<T>(code: string, input: Record<string, unknown> = {},
                 options: Subjected & { key?: string; dryRun?: boolean } = {}) {
  const result = await this.request({
    type: "command", code, input,
    key: options.key ?? this.newKey(),   // a new key on every call
    subject: options.subject, dryRun: options.dryRun,
  });
  return result.value as CommandResult<T>;
}

Line 332 is the root of the retry problem. A key exists end to end, but a second call makes a second key. The server cannot tell a retry from a new change.

// omnium-console/src/lib/api.ts:773-788
export const editFixture = async (id: string, body: FixtureEdit): Promise<Fixture> => {
  const subject = fixtureRef(id);
  if (body.name !== undefined) await send("results.set_name", { name: body.name }, subject);
  if (body.start !== undefined) await send("results.set_start", { start: body.start }, subject);
  if ("venueId" in body) await send("results.set_venue", { venueId: body.venueId ?? null }, subject);
  if (body.status !== undefined || body.official !== undefined) {
    await send("results.set_status", { status: body.status, official: body.official }, subject);
  }
  if ("scoreline" in body) await send("results.set_result", { scoreline: body.scoreline || null }, subject);
  if ("medal" in body) await send("results.set_medal_event", { medal: body.medal ?? null }, subject);
  return readNow(readFixture(id));
};

One command per field, one after another. If the third one is refused, the first two are already saved. Decision V10 replaces this with one results.edit_fixture command: saved whole or not at all.

// omnium-console/src/pages/FixturePage.tsx:178-185
const edit = useMutation({
  mutationFn: (body: FixtureEdit) => editFixture(id, body),
  onSuccess: (next, body) => {
    apply(next);                                   // write the server's record into the cache
    toast.success(savedTitle(body, FIXTURE_WORDS), kept(next));
  },
  onError: fail("Not saved"),                      // a toast, nothing kept
});

A TanStack Query mutation. It has onSuccess and onError but no onMutate, so nothing shows until the server answers. main.tsx:33 sets mutations: { retry: 0 } for the whole app.

On the server side, the key is already honoured. The engine looks for an earlier command with the same key before it runs anything:

# packages/core/src/omnium_core/workflows/engine.py:116-122
await session.execute(sa.select(sa.func.pg_advisory_xact_lock(ledger.lock_key(subject_id))))
stream_id = await streams.stream_for(session, kind, subject_id)

if idempotency_key:
    prior = await _prior_seq(session, stream_id, actor, idempotency_key)
    if prior is not None:
        return CommandOutcome(accepted=True, code=code, duplicate=True, seq=prior)

A unique index on timeline_item (stream_id, source_code, idempotency_key) backs this up (packages/contract/src/omnium_contract/models/timeline.py:58-66). So the server is ready. Only the browser needs to keep the key. The line-by-line walk through commands, rules and actions is on Writing a workflow in code.

The outbox in the browser (agreed, F1 and F2)

IndexedDB is a small database built into every browser. Unlike memory, it survives a crash, a reload and a new deploy. The outbox is one store in it. This record shape is copied from the design doc:

// design doc, Section 7, "On the device" (new; not in the code)
// IndexedDB database "omnium", one store per app origin (the iframe has its own origin)
// store "outbox", key: change id (the command key, made once)
type Pending = {
  key: string;              // crypto.randomUUID(), sent on every retry (Section 4, C2)
  subject: string;          // "fixture:01a0..." - the queue is per subject
  code: string;             // "results.edit_side"
  input: object;
  saw?: Saw;                // the version the screen showed (Section 4, C3)
  createdAt: string;        // order within a subject
  tries: number;
  state: "waiting" | "sending";
};
// index on (subject, createdAt): the next change to send for each subject

The rules for the outbox:

The design names the file packages-ts/omnium-bridge/src/outbox.ts (new). A sketch of one send loop, written from the rules above; it is not code from either repo:

// sketch of the agreed send loop (F2); names are illustrative
async function drain(subject: string) {
  for (;;) {
    const next = await outbox.oldest(subject);         // index (subject, createdAt)
    if (!next) return;
    try {
      const answer = await bridge.command(next.code, next.input,
                                          { key: next.key, subject: refOf(subject) });
      if (answer.conflict) { pause(subject, next, answer); return; }  // V3
      await outbox.delete(next.key);                    // accepted, duplicate, refused
      report(next, answer);                             // saved / refused state
    } catch (networkError) {
      await sleep(backoff(next.tries++));               // 0.2 s doubling to 30 s, plus jitter
    }
  }
}

Showing a change before it is confirmed (agreed, F3)

The console already uses TanStack Query, and every watched read lives in its cache. An optimistic update shows the change on screen before the server confirms it. TanStack Query does this with a mutation's onMutate step. The agreed flow:

// sketch of F3 with the TanStack Query v5 API; not code from the repo
const edit = useMutation({
  mutationFn: (body: FixtureEdit) => change.send("results.edit_fixture", body, saw),
  onMutate: async (body) => {
    await client.cancelQueries({ queryKey: ["fixture", event, id] });
    const before = client.getQueryData<Fixture>(["fixture", event, id]);
    client.setQueryData(["fixture", event, id], { ...before, ...body }); // shows at once
    return { before };
  },
  onError: (_error, _body, context) => {
    client.setQueryData(["fixture", event, id], context?.before);       // roll back
  },
});

Today only the medal table drag works this way, and it rolls back by re-reading (MedalsPage.tsx:102-115).

The five field states (agreed, V2 and V3)

A refusal reads like this: "A medal needs a finished match. Men's 100m Final is still LIVE." It appears next to the field, not only in a toast. Today every refusal is a toast in the corner (FixturePage.tsx:172).

Keep theirs drops your change and shows their value. Use yours sends your value again. The design doc does not spell out how that second send is built; it must carry saw = their version, or it would conflict again.

The hooks that carry the states, as the design doc gives them:

// packages-ts/omnium-bridge/src/react.ts (new hooks; design doc, "The hooks")
type ChangeState = "idle" | "sending" | "saved" | "refused" | "conflict";

function useChange(subject: Subject) {
  // returns send(code, input, saw) and, per field, its state and message
  // send(): writes to the outbox, applies onMutate to the query cache, returns at once
  // the outbox answer updates the state: saved (tick 2 s), refused (sentence), conflict (theirs + yours)
}

function useField<T>(id: string, serverValue: T, version: number) {
  // draft, setDraft, focused; while focused or dirty, serverValue changes do not touch draft
  // changedMeanwhile = serverValue !== startedFrom; save() sends saw = version it started from
}

Today react.ts has useWatch, useRead and useCommand (react.ts:61-138). The console uses its own live() helper instead. The design keeps useCommand for old apps.

The typing guard (agreed, V4 and F4)

Today a text field copies the server value into its draft every time the value changes:

// omnium-console/src/pages/FixturePage.tsx:902-903
const [draft, setDraft] = useState(value);
useEffect(() => setDraft(value), [value]);

If Priya saves the score while Asha is typing, the live push changes value, and Asha's half-typed text is replaced. The start field does the same (FixturePage.tsx:949-952).

One place already guards against this. The medal box keeps its draft while it has focus:

// omnium-console/src/pages/MedalsPage.tsx:1143-1145
useEffect(() => {
  if (!typing) setDraft(String(value));
}, [value, typing]);

The agreed useField makes that the rule for every field, and adds two things the medal box lacks:

1. Each field reports focus and unsaved text to a small registry: its id and the value it started from.
2. A live push still updates the cache. A field in the registry keeps its draft and compares the new value with the one it started from. If they differ, it shows "Changed to 3-1 by Priya while you typed".
3. On save, the field sends saw = the version it started from. If the record moved, the server answers conflict, and the five states take over.

Live updates (built, and agreed changes in F5)

The panel's host re-reads affected watches one after another today:

// packages-ts/omnium-bridge/src/host.ts:215-229 (trimmed)
for (const [watchId, watch] of [...this.watches]) {
  if (!everything && watch.depends && !watch.depends.some((area) => touched.has(area))) continue;
  try {
    const { value, depends } = await this.readWith(watch, watch.name, watch.params); // waits each time
    watch.depends = depends;
    const text = JSON.stringify(value);
    if (!this.watches.has(watchId) || text === watch.last) continue;
    watch.last = text;
    this.post({ type: "push", watchId, value });
  } catch { /* kept: the next change reads it again */ }
}

A page with 7 watches waits for 7 reads in a row. F5 changes this loop to read 4 at a time.

The server ends each stream after 10 s, because the ECS Service Connect proxy cuts every request at 15 s:

# packages/core/src/omnium_core/settings.py:263-267
# Not 0 by default because of AWS: admin-api sits behind ECS Service Connect,
# whose proxy ends EVERY request after 15 seconds unless the service sets a
# timeout. A stream cut there shows "Reconnecting" and can drop a change.
# Ending first, cleanly, avoids both. Set 0 once that timeout is lifted.
stream_max_seconds: float = Field(default=10.0, ge=0)

F5 raises the proxy timeout for the admin service and sets stream_max_seconds to 0. The stream loop itself reads domain_event once a second (_POLL_SECONDS = 1.0, packages/admin/src/omnium_admin/routers/bridge.py:766).

The user asked for more: when two scorers work one match, the second screen should update as soon as the first changes something. Section 8 takes that as its main target: about half a second, pushed with the change itself rather than a re-read. See Bridge and live updates.

Pages that open fast (agreed, V6 and F6)

Every page is imported eagerly today, so the first screen downloads all of them:

// omnium-console/src/App.tsx:6-14
import OverviewPage from "./pages/OverviewPage";
import MedalsPage from "./pages/MedalsPage";
import IntegrationsPage from "./pages/IntegrationsPage";
// ... PlayersPage, PlayerPage, SchedulePage, FixturePage, RunsPage, FeedsPage

The agreed change uses React.lazy, which loads a page's code only when its route opens:

// sketch of F6; not in the repo
const MedalsPage = lazy(() => import("./pages/MedalsPage"));
// <Suspense fallback={<Loading what="Opening…" />}> around <Routes>

A virtual list keeps only the visible rows in the page and swaps them as you scroll. The comment at SchedulePage.tsx:823-825 explains why it is needed: drawing all 895 rows at once "takes long enough to feel like a freeze". The new wrapper is omnium-console/src/components/VirtualList.tsx (new), used by Schedule, Players and Runs.

The scorecard grid and the keyboard (agreed, V7)

The scorecard entry screen is new (omnium-console/src/pages/ScorecardPage.tsx, new). It is a grid: players down, the sport's line keys across. The columns come from the sport's line catalogue (Section 6, P1), so the same screen serves cricket, football or any sport set up in settings. No sport is written into the screen.

Each row saves as one results.set_line command through the outbox, and ticks as it saves. A 22-row cricket scorecard is 22 commands, in order. results.set_line does not exist yet; Section 5 defines it. Ctrl+K and "?" live in omnium-console/src/components/Palette.tsx (new).

Today the console has no shortcuts. Its only key handlers are Escape for drawers and dialogs (ui.tsx:407-410) and Enter or Escape in a field. The cricket desk is the only app with number keys (CricketApp.tsx:701-704).

Role-aware screens (agreed, V8)

The session already says whether this person may write:

// packages-ts/omnium-bridge/src/protocol.ts:83-84
/** Who the log will say it was. */
user: { name: string; role: string | null; canWrite: boolean };

The host refuses a command from a viewer (host.ts:308-310): "Your account can look but not change anything." But the console never reads canWrite (no match for it in omnium-console/src on 7 Oct). So a viewer sees every edit button and is refused only on save. V8 makes viewers get read-only pages with a note: "You can view, not change." Actions like approving a release appear only to those allowed. Section 13 owns the role rules.

One shared UI kit (agreed, V9)

The console's components live in one file, omnium-console/src/components/ui.tsx: Button, IconButton, Stat, Chip, Card, Tabs, Empty, Problem, Note, Loading, Skeleton, Drawer, useToast, useConfirm. The theme uses the Outfit font (src/styles/tokens.css:97). V9 moves this kit, the icons and the tokens into a new package, packages-ts/omnium-ui. The console and the desks both use it. The desks move into the omnium repo as apps/desks and deploy like the console.

Files the design changes

results.edit_fixture (agreed, V10)

packages/flows/src/omnium_flows/results/commands.py holds ten commands today: set_name, set_start, set_venue, set_status, set_result, set_medal_event, add_side, edit_side, remove_side, hand_back (lines 114-198). Each changes one thing. results.edit_fixture (new) takes several fields of one match in one input and runs as one command. One lock, one transaction: saved whole, or not at all. The match page shows one sending mark and one tick for it.

Speed tests (agreed, F7)

"Fast" is a Playwright test in a real browser, run in CI. From the design doc:

// omnium-console/tests/speed.spec.ts (new, Playwright, real Chrome)
test("a score edit shows at once and is confirmed quickly", async ({ page }) => {
  const t0 = Date.now(); await page.getByLabel("Score").fill("3"); await page.keyboard.press("Enter");
  await expect(page.getByTestId("field-score-state")).toHaveAttribute("data-state", "sending");
  expect(Date.now() - t0).toBeLessThan(100);
  await expect(page.getByTestId("field-score-state")).toHaveAttribute("data-state", "saved", { timeout: 1000 });
});

The targets: click to screen under 100 ms, save to tick under 1 s on a local server, page open under 2 s. The console has Playwright tests today (omnium-console/tests/, nine spec files including bridge.spec.ts and medals.spec.ts), but none measures speed, and none covers a dropped, slow or conflicting change.

Tests that prove it

Build order

The design doc gives this order. Each step fixes something on its own.

1. The outbox and useChange in the bridge package; the console's send() goes through it. Fixes retries and lost changes.
2. useField on every text field. Fixes typing being overwritten.
3. results.edit_fixture; editFixture sends one command.
4. The five field states on the match page, then Medals and Players.
5. React.lazy routes and the virtual list.
6. The proxy timeout and parallel re-reads.
7. Viewers get read-only screens.
8. The scorecard grid, Ctrl+K and shortcuts.
9. The shared UI package; the desks move into the repo on it.

When things go wrong

Every case ends with no change lost, none saved twice, and the person knowing where they stand. This is the agreed behaviour. What happens today is in the worked example above and in "Built today, or still to build" below.

Decisions

All 17 decisions are agreed (design doc, closed 6 Oct 2026).

Built today, or still to build

Numbers

Read next

• Bridge and live updates: how the second screen sees a change, and the half-second target from Section 8.
• Commands and the workflow engine: what happens to a command after the panel sends it: key, lock, check, apply, answer.
• Writing a workflow in code: the backend side of a command, line by line.
• Monitoring, logs and alerts: how a failed send or a stuck screen gets noticed.