Goals, users and numbers

What this part does

Section 1 answers five questions before anything is designed. Every later section depends on these answers, so a guess here would be a guess everywhere.

The answers came from the product owner in the design doc's question tables (1.1 to 5.2, F1 to F11, G1 to G6). They are written up below in teaching order, not in the order they were asked.

The users

What we knew before Section 1, from the Asian Games (Aichi–Nagoya, 19 Sep to 4 Oct 2026), our only real load so far:

• No live scorers. Every change came from Scout imports or hand edits in the console. The ball-by-ball scoring screens were built but never used on prod.
• Three media clients. NDTV and News18 got 7 files each, by FTP, SFTP or S3. DailyHunt got the top-5 medal table only, from 30 Sep.
• No targets were written down. No delay target, no uptime target, no "how much data may we lose" target. Real delay from the official site to a client file was minutes: Scout read the site every 1 to 10 minutes, then the send rounds followed.

How it works

The targets sit along the path one score takes, from the scorer's tap to a fan's screen. Each step has one number it must meet, and each number has a reason.

1. The scorer taps. The screen shows the action at once. The round trip from India to our servers in AWS US East is about 200 ms (from the design doc), so the screen must not wait for the server to show it.
2. The device keeps it. The action stays on the scorer's device until the server confirms it. If the venue network drops, scoring goes on, and the actions sync when the network is back (targets 5 and 6).
3. The server saves, then confirms. The server says "saved" only after the save is on disk. This is what makes "no data lost" true from the tap on (target 5). If the database fails over to its standby, clients see at most 2 minutes of extra delay, and scorers keep scoring on their devices (target 6).
4. The sender tells the clients. For APIs and push, 95 in 100 updates reach the client within 2 s of being saved. For FTP and SFTP files, within 10 s. A client's contract may allow slower; nothing faster is promised (target 4).
5. The cache answers fans. Public API reads go through a cache. The database sees a few reads per match per second, however many fans there are. The public API must be ready for 10 million requests a day and peaks of 2,500 a second (target 10).

Around the path there are four more rules. Every action records who did it and from which screen (target 8). Results go out at once by default, and a checker step can be switched on per sport or client later (target 7). A new client feed, provider or sport is added by settings, in 1, 3 and 5 days (target 11). And one person is on duty, with a minimum set of alerts, on every live day (D8).

A worked example

Low-level design

The eleven targets

These are the targets agreed in Section 1. Every later section is checked against them. Each one says what it means and why it is set where it is.

What targets 5 and 6 cost

Decision D11 says "never lose data" and "no downtime" mean exactly targets 5 and 6, and we test them. The design doc names the price plainly:

• a queue on the scorer's device, so actions survive a network drop;
• a standby database in a second zone, which is where the 2-minute failover comes from;
• two copies of every service, and releases that swap one copy at a time.

The device queue also explains decision D10. "Any device" includes Safari on iPhone and iPad, and Safari can delete data a site keeps on the device after 7 days with no visit, and when a private window closes. So the console works in any modern browser, but three setups are tested and certified for live scoring: Chrome on a laptop, Safari on an iPad, and Chrome on an Android phone. The console warns when it cannot keep data on the device.

The load, worked out

The arithmetic behind targets 3 and 10:

seconds in a day                     86,400
1 million requests a day   -> about     12 a second   (1,000,000 / 86,400)
10 million requests a day  -> about    116 a second   (10,000,000 / 86,400)
a goal spike, 10 to 20 times average  (estimate, design doc; no data yet)
20 x 116                   -> about  2,320 a second   -> target peak 2,500 a second

The point of the design doc's view 8: the load is small; correctness and delivery are the hard parts. The writes are a few actions a second. The real load is on the way out: many clients, many formats, and public APIs on client websites. Every public read needs a cache in front of it.

Who did what: the log today

Every change in omnium today is a workflow command, and every command lands as one row in timeline_item before any writer runs. The row carries who sent it. This is the base target 8 builds on.

# packages/core/src/omnium_core/workflows/records.py:45-62
PERSON = "person"
INTEGRATION = "integration"


@dataclass(frozen=True, slots=True)
class Actor:
    """Who sent a command."""

    #: ``person`` or ``integration``.
    kind: str
    #: What the log shows: an account's name, or ``integration:<code>``.
    name: str
    #: ``timeline_item.source_code``: the account id, or the integration code.
    source_code: str | None = None
    ...

Actor is the sender of one command. kind says whether a person or an integration (a Scout import) sent it. name is what the log shows. source_code is the id that makes a retry safe: two senders can each use the same idempotency key without clashing.

# packages/core/src/omnium_core/workflows/engine.py:141-154
item = TimelineItem(
    stream_id=stream_id,
    fixture_id=fixture.id if fixture is not None else None,
    source_code=actor.source_code,
    event_type=code,
    unit=UNIT,
    seq=await streams.next_seq(session, kind, subject_id),
    status=TimelineItemStatus.CONFIRMED,
    occurred_at=datetime.now(UTC),
    payload=_logged(node.impl, payload),
    idempotency_key=idempotency_key,
    actor=actor.name,
)

This is where the log row is made. actor and source_code record who sent it. seq is the next number in this match's (or event's) log. idempotency_key is the client's own id for the action, so a re-send is spotted and not applied twice. For how commands, validations and actions are written, see Writing a workflow in code.

Two gaps against target 8, both checked in the code:

# packages/admin/src/omnium_admin/auth.py:31, 52-56
NO_LOGIN = "admin"
...
    @property
    def actor(self) -> Actor:
        """A person, for the workflow engine. The account id is what makes a retry safe."""
        source = f"account:{self.signed_in.account_id}" if self.signed_in is not None else None
        return Actor(kind=PERSON, name=self.name, source_code=source)

• The person can be "admin". When nobody is signed in, the log says admin and source_code is empty. Sign-in is off by default: admin_auth_required: bool = False (packages/core/src/omnium_core/settings.py:56).
• The screen is not recorded. timeline_item has actor and source_code (packages/contract/src/omnium_contract/models/timeline.py:76-78) but no column for the app or screen the command came from.

Sources and priority: the pin today

Decision D6 (a higher source beats a lower one) is settled in Section 2. Today there is one built level of priority: a person beats an import. A field a person set in the console is "pinned", and imports leave it alone.

# packages/core/src/omnium_core/ingest/fixtures.py:1141-1150
pinned = set(row.pinned or [])
changed = False

def allowed(name: str, same: bool) -> bool:
    if same:
        return False
    if name in pinned:
        report.kept_by_hand += 1
        return False
    return True

For each field an import wants to change, allowed asks two things. Is the value the same? Then skip it. Did a person pin this field? Then keep the person's value and count it in kept_by_hand. The pin lists live on fixture.pinned and fixture_competitor.pinned (see the module note at packages/core/src/omnium_core/ingest/fixtures.py:33-38).

Provider feeds: not built today

Decision D5 says provider data takes the same road as scorer data: no side road, raw data kept. Today, the only no-code source is a Scout job. An integration row connects one Scout job to one workflow's import command (packages/contract/src/omnium_contract/models/integrations.py:27-43, with scout_job_id at line 43). The seam meant for live provider feeds does nothing yet:

# packages/worker/src/omnium_worker/ingest/runner.py:293-299
async def _fold_command_stub(fixture_id: uuid.UUID, record: RawRecord) -> None:
    """Tier-1 fold seam — no-op until the provider sample lands.

    The real mapper turns ``record.payload`` into a scoring command,
    ``ledger.append``s it and enqueues the scoring job (which folds).
    """
    return None

A provider message that reaches this seam is turned into nothing. Agreed design, not in the code yet: each provider is registered once by settings (address, login, push or pull, how often), its raw data is kept, and each message becomes the same commands a scorer sends.

Delay to clients: what the code does today

Target 4 is measured from the save. Today's path to a client file has three timers, all settings with these defaults:

# packages/core/src/omnium_core/settings.py:143, 154, 238
feed_debounce_seconds: float = 1.0     # a burst of writes -> one feed rebuild per window
feed_rebuild_seconds: float = 60.0     # sweep: is any event's data newer than its feeds?
delivery_poll_seconds: float = 5.0     # sender asks "who is owed a file?"

• feed_debounce_seconds joins a burst of writes into one feed rebuild per second.
• feed_rebuild_seconds is a safety sweep. Writes from another process (such as imports) may not reach the feed engine directly, so once a minute the delivery worker checks for feeds behind their data.
• delivery_poll_seconds is how often the sender reads the database to find clients who are owed a newer file (packages/core/src/omnium_core/publishing/delivery/dispatcher.py:1-27).

Read from these settings alone (an estimate, not a measurement), a console edit can reach an FTP client in about 1 s plus up to 5 s plus the upload, which fits the 10 s target on paper. A change that waits for the 60 s sweep does not. Neither path is measured end to end today: not checked. The 2 s target for APIs and push needs a different path, designed in Stats, feeds and delivery.

Public reads: the cache today

Target 10 needs a cache in front of every public read. Today the public API has a Redis cache with time limits by how fast the data changes:

# packages/core/src/omnium_core/settings.py:77, 92-103
redis_url: str | None = None
...
cache_ttl_live: int = 3
cache_ttl_scheduled: int = 60
cache_ttl_final: int = 21_600  # 6h
cache_ttl_reference: int = 3_600  # 1h
cache_ttl_leaderboard: int = 60
cache_ttl_negative: int = 45
cache_stale_window: int = 30

Live data is kept 3 s, finished results 6 hours. cache_stale_window lets a key be served for 30 s more while it is refreshed in the background. redis_url is optional, so an environment with no Redis has no cache at all. The 10-million-a-day and 2,500-a-second figures have not been load-tested on this branch: not checked.

Adding things by settings (target 11)

When things go wrong

What each failure must look like when the targets are met (agreed design):

Decisions

All fifteen were agreed on 3 Oct 2026. D12 to D15 came from answers G1 to G4.

Built today, or still to build

Checked against the si-build-omnium code on 7 Oct 2026 (branch feat/result-feeds, commit 76ef1e2).

Numbers

Read next

• The big picture: every part of omnium on one page.
• Life of a score: one goal from tap to client file, step by step.
• Truth and ownership: Section 2, where the priority rule (D6) is settled.
• Commands and the workflow engine: the one road every change takes, and the command-time numbers.
• Stats, feeds and delivery: how the 2 s and 10 s targets are met.