Start here · Words

Glossary

Every word these docs use, in one plain sentence each.

Covers: Terms from all pages
Order: By topic, then A to Z inside each topic

In one minute

If a page uses a word you do not know, it is here. Each entry says what the thing is, then where to read more.

The data

Word	Meaning
Archetype	The shape of a sport's result. Every sport is `HEAD_TO_HEAD` or `RANKED_FIELD`. See The data model.
`HEAD_TO_HEAD`	Two sides play each other, and the result is a score. Football, boxing, volleyball.
`RANKED_FIELD`	Many competitors, and the result is a ranking. A 100 m final, a swimming heat.
`AGGREGATE_CLASSIFICATION`	A table built from many results: standings, group tables, the medal table. It sits on top of both archetypes.
Competition	An event or a part of one: a Games, a sport inside it, a stage, a group. Competitions form a tree.
Fixture	One match, heat, bout or final. The `fixture` table.
Side	One competitor in a fixture: a team, a player, a pair. Rows in `fixture_competitor`.
Participant	A person, team or country, kept once and shared by every sport. The `participant` table.
External id	A provider's own id for one of our records, mapped in `external_id_map`.
`meta`	A JSONB column for sport-specific data, used instead of adding sport-specific columns.

Services

The six services in the plan (decided 7 Oct 2026). See The big picture.

Word	Meaning
admin-api	The service behind the console's screens and settings. In the plan it runs no commands and no imports; it only receives Scout's doorbell and puts the import job on the queue.
Alert service	Its own small service that turns problems into one alert each and sends it (Section 11). One working copy at a time.
Command service	Runs every command from scorers and the console, inside the HTTP request. Two copies (Section 4, L15). Scout imports also run here, in a process of their own at lower CPU priority (8 Oct).
Delivery-worker	Builds client files from the main database and sends them, one queue per destination. It also writes everything that is pulled (client files and public match documents) into Redis. Section 9 calls its build step "the publisher".
publishing-api	The public API: reads for fans and apps, and client pull from Redis.
Scheduler	Today's container for timed jobs and imports. Removed in the plan on 7 Oct 2026; its timed jobs moved to the stats-worker and its imports to the command service.
Stats-worker	Counts stats and runs the timed jobs. Each of its loops beats on its own.

Writing a change

Word	Meaning
Action	The code that changes the data once a command has passed its checks. See Writing a workflow in code.
Bridge	The one protocol between apps and the admin panel. Every app change goes through it. See Bridge and live updates.
Command	A request to change something, with a code (what to do), an input (the values) and a key. See Commands.
Command key	An id the sender picks for one command. Sending the same key again never applies the change twice.
Conflict	One of the five answers: someone else changed the record after you read it.
Duplicate	One of the five answers: this key was already applied, and here is the same answer as before.
Five answers	What a sender can get back: accepted, duplicate, refused, conflict, try again.
Idempotent	Safe to repeat: doing it twice has the same effect as doing it once.
Lock	A hold on a database row, so two changes to the same match wait for each other instead of mixing.
Outbox	A table of "this happened" rows, saved in the same transaction as the change. Readers follow it to learn of changes.
Refused	One of the five answers: the command broke a rule, and the answer says which.
Transaction	A group of writes saved all together or not at all.
Try again	One of the five answers: something on our side failed; resend with the same key.
Validation	A check a command must pass before its action runs, such as "the score cannot be negative".
Version check	Before applying, the engine checks the record is still at the version the sender saw. If not, the answer is conflict.
Workflow	A named set of commands, validations and actions for one kind of record: a sport's scoring, an event's operations, or results.
Workflow engine	The core code that runs every command: lock, check, apply, save, answer.

Scoring

Word	Meaning
Apply mode	The default way of scoring: a person sets the scorecard or a value directly. Most sports and all operations use it.
Checkpoint	A saved copy of a match's state at a point in its log, so a replay can start from there.
Events mode	Scoring event by event (each ball, each point), for the few sports that need it.
Replay check	A background job that rebuilds a match from its log and compares it with the saved state.
Saved state	The current state of a match, kept in its `scoreboard` row, so a new event needs only one small step.
Scorecard	The lines of a result, set by a person: sets, games, times, places.
Step function	A sport's rule code: given the state and one event, return the new state.

Sport plugins

Word	Meaning
Canary	Trying a new release on one competition first, before everyone.
`code_sha`	A fingerprint of the exact plugin code that scored a match, so we always know which rules were used.
Golden	A recorded match kept as a test: replaying it must always give the same answers.
Plugin	A sport's rules and stats as installable code, in the flows package. See Sport plugins.
Registry	How the engine finds installed plugins, without naming them in code.
Release pin	Each match stays on the plugin release it started with, so a new release never changes a match half-way.

Imports

Word	Meaning
Field pin	A mark on a field that a person set by hand, so an import does not overwrite it. See Truth and ownership.
Guard	A check that holds an import run for review when its effect looks wrong.
Integration	A no-code setup that turns a Scout job's rows into commands.
Run	One pass of an integration: fetch the rows, compare, send commands.
Scout	Our separate service that fetches provider websites and hands back rows.

Getting data out

Word	Meaning
Assignment	One client's subscription to one feed at one destination. A row in `delivery_assignment`.
Coalescing	When several versions of a file wait for one destination, only the newest is sent.
Content hash	A fingerprint of a file's bytes. Same hash, nothing to send.
Destination	Where a client's file goes: an FTP or SFTP folder, an S3 bucket or a webhook.
ETag and 304	A file's version tag. A client that already has it gets "304 Not Modified" and no body.
Feed	A file in a shape a client agreed: the medal table, the calendar, a match's result.
Proof of delivery	The record of what version each destination got, when, and the receipt it gave.
Publisher	Section 9's name for the step that builds client files. In the plan it runs inside the delivery-worker, not as its own service (decided 7 Oct 2026).
Pull	The client calls our API for a file.
Push	We send the file to the client.
Write if newer	Redis keeps a file only if its version is newer than the one it holds, so an old file never replaces a new one.

Live updates

Word	Meaning
`LISTEN` and `NOTIFY`	Postgres's built-in signal: one connection says "something changed", listeners wake up at once.
SSE	Server-sent events: one open web connection the server writes updates down.
Watch	A screen's standing question ("this match"), answered again whenever the answer changes.

The database

Word	Meaning
Heartbeat row	One row the main database updates every second, so we can measure how far behind the copy is.
HOT update	A Postgres update that rewrites a row in place without touching indexes. It keeps rows that change on every ball cheap.
Lag	How far the read-only copy is behind the main database, in time.
Partition	One slice of a big table, here usually one month. Old months are dropped whole.
Read-only copy	A second database that receives every change from the main one and serves reads only. Also called a read replica.
Retention	How long a kind of data is kept before it is removed.
WAL	The write-ahead log: Postgres's record of every change, which the copy replays.

Monitoring

Word	Meaning
Alert	One open problem, with a key, a count and a state.
Alert signal	One row saying "this went wrong once". Many signals fold into one alert.
Condition rule	A rule checked every 15 s against our own numbers, such as "a destination is over 60 s behind".
Event rule	A rule raised by code at the moment something fails.
Process beat	A row each background process updates every 10 s, so we know it is alive and working.
Trace id	One id carried from the first request through every service and log line.