Terminology
This vocabulary is authoritative for the rest of the document, the
codebase (pkgs/bigfred/server/domain, services, security policies), the REST
endpoints, the WebSocket protocol and the MCP tool names. Whenever the
domain meaning differs from the casual English word, the table below
wins.
| Term | Polish / domain meaning | Where it appears |
|---|---|---|
| driver | Maszynista – a user who operates vehicles and trains. Owns the throttle for their own vehicles and for vehicles currently leased to them. Enters throttle mode (§1) to drive. | Role driver; UI throttle mode; security inputs Actor when applicable. |
| signalman | Nastawniczy – a user who directs train traffic from a signal box (interlocking), issues entry/departure decisions, and may take over a driver's vehicle or train to re-park it when operationally necessary. | Role signalman; Interlocking/InterlockingSession; TakeoverRequest. |
| vehicle | A single rail vehicle the system tracks. Carries a kind picked from a closed catalogue (loco – lokomotywa, emu – EZT, driving_wagon – wagon sterowniczy, trolley – drezyna, wagon – wagon), an optional free-text number (e.g. a wagon road-number or the inventory number stamped on a locomotive), and an optional DCC address. When the DCC address is set the vehicle is steerable from a throttle (the usual case for a loco/emu/driving_wagon/trolley); when it is absent the vehicle is a dummy – it can still be added to a train and shown on the layout vehicle roster, but the throttle never speaks DCC against it (typical for unpowered wagons and unmotorised dummies dragged behind a loco for length/visual purposes). |
domain.Vehicle, domain.VehicleKind; REST /api/v1/vehicles; WS loco.* (kept for DCC-protocol compatibility, fired only for vehicles that carry a DCC address). |
| train | Skład – an ordered group of 1 or more vehicles owned by a user, addressed and driven as a single unit. Trains can be leased like a single vehicle. | domain.Train, domain.TrainMember, domain.TrainLease; REST /api/v1/trains; WS train.*. |
| interlocking | Nastawnia – a logical signal box. At most one signalman occupies a given interlocking at a time. Visibility is scoped to the layout the driver is currently in (see layout). Signalmen open a three-panel interlocking view from the dashboard to staff the box: a fixed-width, scrollable radio chat panel on the left (every message exchanged with every driver in the layout, group-chat style), a fixed-width, scrollable, searchable vehicle/train roster panel in the centre with per-row radio, stop and takeover actions, and a fixed-width, scrollable train announcements panel on the right (§6.3d). A second signalman may displace the current occupant after explicit confirmation (§6.3d). | domain.Interlocking, domain.InterlockingSession, domain.LayoutInterlocking; UI InterlockingPage; REST POST /api/v1/interlockings/{id}/join; WS interlocking.occupantChanged. |
| train announcement | Zapowiedź pociągu – a pre-recorded station PA message listed in a static frontend manifest (web/src/config/trainAnnouncements.ts). The signalman selects an entry from the train announcements panel; the client plays the matching Ogg file locally on the clicking device only (/sounds/train-announcements/{soundKey}.ogg). Distinct from radio (walkie-talkie phrases to drivers): no backend persistence, no WebSocket fan-out, no audit entry. |
UI <InterlockingTrainAnnouncementsPanel>, config/trainAnnouncements.ts; assets web/public/sounds/train-announcements/. |
| takeover | A signalman taking driving authority over a driver's vehicle or train. There is a 15-second window for the driver to reject; if the driver does not reject in time the takeover is granted automatically. On grant the system creates a 5-minute self-lease (§ lease) to the signalman, the affected driver's throttle session for that target ends (they are redirected to the dashboard and the target disappears from their throttle picker for the lease duration), and the signalman drives the target inside a closable throttle overlay that can only be closed once the target's speed is 0 (§6.3d). | domain.TakeoverRequest, domain.VehicleLease / domain.TrainLease (the 5-min grant lease); WS takeover.*. |
| lease | A time-bounded permission to drive somebody else's vehicle or train. Lease never grants edit rights. A takeover (§ takeover) materialises as a self-issued lease of 5 minutes (takeover constant) from the target's owner to the signalman. |
domain.VehicleLease, domain.TrainLease. |
| radio | "Walkie-talkie" channel between drivers and signalmen, built on a closed vocabulary of standard phrases. Every message is exchanged in the context of a specific vehicle XOR train and addressed to a user XOR an interlocking. Messages are stored only in Redis with a default 4-hour TTL (no SQLite persistence); they are ordered by time and replayed from Redis on reconnect. Sending plays /sounds/interlockings/radio-sent.ogg for the sender; the receiver hears /sounds/interlockings/{phrase}.ogg (per-phrase asset). |
domain.RadioMessage (Redis-only value type), domain.RadioPhrase; WS radio.*. |
| radio stop | Radiostop – a layout-wide emergency halt triggered deliberately by a user with drive authority. Two coordinated effects (§4.6.1a): stops every vehicle on the layout roster (all command stations) and fires every connected driver's dead-man's-switch emergency plan (clamped to the stop_my_vehicles…release_my_leases band). Plays a radiostop alarm sound on every open throttle session. Distinct from per-session system.estop, admin-only estop_all, and the walkie-talkie phrase STOP_IMMEDIATELY. |
WS system.radioStop; UI throttle overlay left-toolbar button + confirm overlay (§6.3b); sound /sounds/radiostop.ogg; audit system.radio_stop; §4.6. |
| layout | Makieta – a modeling event / room. Picked by the user on the login form, alongside login and PIN, from a dropdown of currently available layouts. A drive session is pinned to that layout at login time and the layout cannot be changed for the lifetime of the session (the user must log out and log back in to switch). Every layout owns its own list of signalmen, its own whitelist of interlockings, and its own set of one or more attached command stations (see command station). An admin may lock any non-system layout: a locked layout is hidden from the login dropdown so no new sessions open in it, but already-running sessions stay alive. The system-provided system layout (Name = "default", IsSystem = true, displayed as "Domyślna (warsztat)" in Polish / "Default (workshop)" in English via the layout:system_default_label i18n key) is always present, cannot be locked, cannot be deleted, and exposes every command station in the catalogue with its set non-editable – making it the always-available fallback. |
domain.Layout, domain.LayoutSignalman, domain.LayoutInterlocking, domain.LayoutCommandStation; REST /api/v1/layouts, /api/v1/layouts/login, /api/v1/layouts/{id}/lock, /api/v1/layouts/{id}/command-stations; WS session.opened { layoutId, availableCommandStations, … }, session.setCommandStation. |
| command station | Centralka – a physical DCC command station, paired with a connection definition (loconet_serial / z21 / loconet_tcp). A command station may be attached to any number of layouts; in particular the system layout always exposes every command station in the catalogue. Inside the throttle (vehicle control view) the driver picks one command station from the session layout's set via a dropdown, and the throttle is gated until a pick is made. Switching the pick mid-session is a controlled context switch (the emergency plan runs against the previous command station first). Command stations are admin-only to create/edit/delete; their attachment to a non-system layout is admin-only too. |
domain.CommandStation, domain.CommandStationConnection; REST /api/v1/command-stations; WS session.setCommandStation, session.commandStationChanged. |
| function | A single DCC function slot on a vehicle, in the range F0–F31. Carries a user-given title (tytuł, wire field name), an icon from the closed catalogue (§3a.8) and a position controlling display order on the throttle. Persisted in dcc_functions with either vehicle_id or template_id set (never both). A vehicle exposes any subset of the 32 slots; the lessee can invoke them but not edit. |
domain.DccFunction, domain.FunctionIcon; table dcc_functions; REST /api/v1/vehicles/{addr}/functions; UI §6.3e. |
| vehicle template | Szablon pojazdu – a reusable function-list definition for a class of vehicles. Its slots are rows in dcc_functions with template_id set. Linked vehicles inherit the list live; the first edit a user makes on their vehicle's functions detaches it via copy-on-write (§3a.6). |
domain.VehicleTemplate; REST /api/v1/vehicle-templates. |
| script | Skrypt – a short JavaScript (ES5.1+) program authored by a user and executed server-side inside a sandboxed Goja VM. The VM runs inside the sibling scripts-executor process, never inside server, so a misbehaving script cannot affect the main throttle. Attached to a single vehicle or a single train and surfaced on the throttle UI as an additional button with an icon from the function-icon catalogue. Every DSL call (findFirstLoco, findByDCCAddr, setSpeed, funcOn/Off, sleep, …) routes through the same LocoService / TrainService and the same security policies as a manual throttle press, so authorization, audit and the dead-man's switch contract are unchanged. |
domain.Script, domain.ScriptAttachment; REST /api/v1/scripts; WS script.run / script.stop / script.log / script.runStarted / script.runStopped; RPC over pkgs/bigfred/server/executor. |
| throttle mode | Tryb sterowania „Throttle” – the real-time driving mode of the BigFred UI. A driver uses it for vehicles they own or hold under lease; a signalman may enter it only after a successful takeover grants driving authority over the target vehicle or train (including the emergency re-parking case). While in throttle mode the operator can toggle DCC functions, start and stop scripts, set speed and direction, trigger per-session emergency braking (system.estop), and trigger layout-wide Radio Stop (system.radioStop, §4.6). Communication with the backend is real-time over WebSocket. The attached command station is the source of truth for movement state: a parallel physical throttle, another BigFred session, or an API/MCP client may control the same DCC address at the same time, so when speed or functions change on the server the UI must reflect the new values (enabled functions, slider position) via push events such as loco.state — local optimistic state alone is never authoritative. In the app shell, throttle mode is opened from the top AppBar via a „Throttle” button with an engineer (maszynista) icon; it renders as a full-screen overlay that covers the rest of the application while the AppBar stays visible, so the user can leave throttle mode or reach account-level actions without losing session context. |
UI ThrottleOverlay, LocoControlPage, TrainControlPage; WS loco.*, train.*, script.*, system.estop, system.radioStop; §6.3b. |
| dashboard | Strona główna / pulpit makiety – the default authenticated landing page (/, HomePage.tsx) shown immediately after login. Presents three live tables scoped to the user's active layout: the layout vehicle roster, online users, and interlockings (with current occupant). Serves as the entry point for adding vehicles to the layout and for opening an interlocking view. |
UI HomePage; REST /api/v1/layouts/{id}/vehicles, /api/v1/layouts/{id}/presence; WS layout.presenceChanged, interlocking.occupantChanged; §6.3c. |
| layout vehicle roster | Pojazdy dodane do makiety – the set of vehicles explicitly attached to a layout via LayoutVehicle rows. Distinct from global vehicle registration: a user first registers a vehicle in the catalogue, then adds it to the layout they are logged into so it appears on the dashboard and is visible to other participants in that operating session. Only the vehicle owner may add or remove their vehicle from a layout. |
domain.LayoutVehicle; REST POST/DELETE /api/v1/layouts/{id}/vehicles; §6.3c. |
| layout admin PIN | PIN administracyjny makiety – a numeric secret bound to a single layout (default length 4–8 digits). It gates BOTH the sudo elevation flow (closed-padlock icon → 2-minute admin promotion) and the signalman self-grant flow (engineer-cap icon → permanent layout-scoped signalman row). Stored as Layout.AdminPINHash (argon2id, per-row salt); plaintext never leaves the dialog. Resettable by any effective admin (sudo or permanent) in the layout settings page (PUT /api/v1/layouts/{id} with an adminPin field) – an empty/missing field never overwrites the existing hash. One PIN per layout, including the system layout. |
domain.Layout.AdminPINHash; REST PUT /api/v1/layouts/{id} (admin only), POST /api/v1/layouts/{id}/sudo, POST /api/v1/layouts/{id}/signalman; §7a.7. |
| sudo elevation | Awans tymczasowy „sudo" – a short-lived (default 2 minutes, configurable in [1m, 10m]) layout-scoped self-grant that lets an authenticated user act as admin after typing the layout admin PIN. A sudo admin grants the same authority as a permanent admin everywhere: there is no operation a permanent admin can do that a sudo admin cannot, including rotating the layout PIN itself. Surfaced on the top AppBar as a closed-padlock icon that flips to open with a live MM:SS countdown badge while active. Mirrored across every WebSocket session of the user via auth.elevationChanged. The 2-minute window plus the rate-limiter on the PIN dialog are the only guard rails. The engineer-cap icon next to the padlock is a separate affordance: it gates a permanent signalman self-grant (layout_signalmen row with expires_at = NULL) behind the same PIN, but it never expires on its own — click again or call DELETE to step down. |
domain.SudoElevation; REST POST/DELETE /api/v1/layouts/{id}/sudo, POST/DELETE /api/v1/layouts/{id}/signalman; WS auth.elevationChanged; §7a.7. |
Note on naming consistency: the wire protocol uses identifiers
prefixed with loco.* (e.g. loco.setSpeed) because at the DCC
protocol level "loco" is the established term and the existing
pkgs/loco/commandstation.Station interface speaks in LocoAddr. The
application domain prefers vehicle because it covers more than
locomotives (EMUs, powered wagons). Both terms refer to the same thing
when applied to a single rail vehicle.