CreatorStudio Suite — Documentation

One consolidated document, generated from the repo's source docs. It always reflects the current sources: the portal assembles it live for the Documentation Center (/docs), and npm run docs regenerates DOCUMENTATION.md + DOCUMENTATION.html for offline distribution. Edit the individual docs listed below — never this built file.

Contents

• Overview & Benefits — OVERVIEW.md
• Screens & Features — SCREENS.md
• Product Requirements (PRD) — PRD.md
• Functional Specification — FUNCTIONAL-SPEC.md
• Architecture — ARCHITECTURE.md
• Scaling — SCALING.md
• On-Vehicle Deployment — ON-VEHICLE.md
• Hanover LED Signs — HANOVER-SIGNS.md
• Security — SECURITY.md
• Licensing & Packaging — LICENSE-PACKAGING.md
• Test Report — TEST-REPORT.md
• Setup & Reference — README.md

CreatorStudio Suite — Overview

CreatorStudio is a complete passenger-announcement platform for public transit. One team authors what the whole fleet says — the stops, the connections, the safety and service messages — in a visual web app, presses Publish, and every vehicle immediately speaks and displays the right thing at the right moment, in the right language, with a tamper-evident record of what each passenger actually heard.

It replaces per-vehicle programming and vendor-locked hardware workflows with one authoring tool, one always-on engine, and open standards (MQTT PIS-PT in; ADT audio + LED/TFT sign frames out). It runs in the cloud for a whole operator or as a single container on the vehicle — same software either way.

What it does — at a glance

The suite — how the pieces fit

• The MQTT broker is the integration hub — the topics are the API. Everything talks through it: the live PT-PIS journey feed comes in, the Engine's audio + LED frames go out to the vehicles, and the dashboard rides the same topics to monitor and control the fleet.
• On the vehicle, the Passenger information app (the browser /player) shows riders the live journey — current and next stop, route and destination — while the vehicle player (headless Go/Python, or the same browser page) makes the sound and drives the interior/exterior LED signs. Both render straight from the broker's topics; nothing else needs installing.
• CreatorStudio (authoring — playlists, LED signs, triggers, voices, and the route simulator) and the Web dashboard (one Monitor cockpit with the map, the fleet feed and the live sign previews in a drawer, plus diagnostics, proof of play and history) are browser apps sharing one design system — and one portal, which also publishes the Documentation Center.
• The Engine turns the trip feed into audio and matrix sign frames (Luminator MatrixRenderer-compatible layouts, real FNT fonts, mono/RGB Mobitec FF and Hanover HCPS/SuperX — sign-vendor independent) and reads its config live from Azure PostgreSQL (pg_notify/LISTEN) — a Publish hot-swaps the fleet in ~1 s with no redeploy. Voices are synthesized once via the TTS cloud and cached fleet-wide.

How an announcement happens

From a live trip signal to sound on the bus and pixels on the signs — one pass through the engine:

Only state-changing signals wake the trigger engine (the high-frequency GNSS firehose is gated), identical phrases are synthesized once for the whole fleet and reused from the cache, and the played-ack closes the loop so the audit records what a passenger actually heard — not just what was dispatched. Sign faces resolve through the same trigger: a firing trigger can override the layout on each vehicle face; otherwise the bound Display cycles pick the active layout from live journey state.

Customer benefits

• Accessibility compliance you can prove. Every announcement and sign change is recorded — dispatched vs vehicle-confirmed, with location, timestamp and transcript — and exportable as a signed proof pack. When a regulator or a rider asks "did the stop get announced?", you have the evidence.
• One tool for the whole fleet. Author once, Publish once; the change reaches every vehicle instantly over the air. No per-vehicle programming, no field visits, no re-flashing signs.
• No vendor lock-in on voices. Compare Azure, ElevenLabs and Acapela side-by-side and switch suppliers without touching a single announcement. ~50 neural voices, a dozen languages, bilingual stops.
• Resilient by design. TTS retries, a circuit breaker and fallback audio keep the fleet talking when a supplier wobbles; if the cloud is unreachable the engine keeps running on the last-known-good config.
• Scales without re-work. Identical phrases are synthesized once and reused fleet-wide, so cost and latency stay flat as vehicles are added — thousands of vehicles from one engine.
• Deploy anywhere. Run it centrally for an operator, or as a single hardened container on the vehicle (multi-arch, non-root) for on-board autonomy — the same software, your choice.
• A better passenger experience. Clear spoken announcements plus a live, branded passenger information screen (current/next stop, countdown, a personal "getting off at" alert) that works on any device.
• Signs as first-class content. Design destination and interior LED layouts the same way you design playlists — visual editor, trigger-driven cycles, Ultima vehicle roster — and ship them as the same MatrixRenderer / Mobitec FF content the Luminator Suite already understands. Sign hardware is vendor-independent: the identical rendered pixels also drive Hanover LED destination signs (HCPS/SuperX graphic frames), so mixed Luminator + Hanover fleets run from one pipeline.

Where to go next

This documentation is ordered high-level first, then progressively deeper into the technical detail:

1. Screens & Features — a visual tour of every screen and what it does.
2. Functional Specification — what the system does, in requirement-level detail (actors, use cases, functional & non-functional requirements, data model).
3. Architecture — how it's built: backend/client architecture, software design, interfaces, the runtime sequence, performance and security.
4. Scaling — the numbers and the knobs behind "thousands of vehicles from one engine".
5. On-Vehicle Deployment — running the engine as a container on the bus.
6. Setup & Reference — install, configure, run and deploy (developer/operator reference).

CreatorStudio Suite — Screens & Features

A visual tour of the product. The suite is three web apps behind one portal: CreatorStudio (design what the fleet says), the Engine dashboard (watch it run and prove it), and the Vehicle player (hear it on the bus). Every image below is a live view of the running apps — captured 12 August 2026 (a few panels 31 July) from a cloud deployment of the suite (an Azure VM) riding the live Baltimore MTA feed — on the August day of capture the engine was tracking 7 300+ real vehicles, 3 077 of them on a journey — alongside an Arriva rail trigger configuration and a Vilnius (Judu) LED-sign set, so each screen shows the product operating on real fleet data, not a staged demo.

Platform home

In the capture: the portal home in its dark theme. Each card states its promise in one line — the Documentation Center's "Every document in one place", the Player's "plays that vehicle's announcements the instant the engine speaks them, and reports back what actually played", the LED Signs card's "rendered with the exact pixels the engine drives the real signs with" — with capability chips (Playlists, Triggers, TTS & SSML, Lexicon; Any device, No install; Pixel-identical, Kiosk ready) summarising what waits behind each door.

The portal landing page — five doors into the suite from one origin: the Documentation Center (every document, one place), CreatorStudio to author announcements, the Engine Monitor to watch the live fleet, the Vehicle Player to turn any device into a bus speaker, and LED Signs to turn any screen into a vehicle's sign. One sign-in, one design system, everything served together — and the same doors are always one click away on the suite rail inside each app.

Documentation Center

/docs — the one entry point for everything written about the platform: the handbook (this document and its siblings stitched into one continuous read, assembled live from the repo on every request, so it can never go stale against a build), the stakeholder and showcase decks, the printable leave-behinds, and the raw sources. Chapters deep-link, and the Markdown is served raw for anyone who wants to diff it. Neither app carries a documentation panel of its own — they link here, so there is exactly one published copy.

In the capture: the handbook's chapters — Overview & Benefits through Architecture, Hanover LED Signs, Security, Licensing & Packaging, Test Report and Setup & Reference — each a tile naming the source file it is assembled from, under the two ways in: "Read in the browser" and the raw live Markdown. (Captured before the newest chapter joined: the as-built Product Requirements — PRD.md — now sits as section 3, between Screens & Features and the Functional Specification.)

In the capture: the presentations grid — the 28-slide Product Deck (arrow keys to present, N for presenter notes, ?print for PDF), the Stakeholder Master Deck, the Showcase Presentation, System Overview & Architecture, the printable leaflet and one-pager, the Software Team Briefing, and "Built with AI — By the Numbers", the measured record of this product's own build.

In the capture: the bottom of the page states the contract — the handbook is generated, so you edit the sources (OVERVIEW.md, SCREENS.md, ARCHITECTURE.md…) and never the built output — and "Where things live" maps the repo: docs at the root, screenshots under docs/media/, decks under docs/showcase/. This page is the only place the docs are published; every app's Documentation link comes back here.

User Manual

/manual — the Documentation Center's learn-by-doing companion (added after the capture above, so the portal now has six doors): an interactive, use-case-based user manual embedded in the suite. Each guide is a goal a real user walks in with — "make the bus announce the next stop", "fix a mispronounced stop name", "prove what passengers actually heard" — and walks the real screens step by step over the same live screenshot set this document embeds, with a deep link into the running app at the moment each step needs it. Guides are searchable ("What do you want to do?"), filterable by topic, and tickable — per-step progress lives in the browser, so a new author can work through the catalogue over days. The suite rail carries a Manual entry at its foot in both Angular apps, so help is one click away from inside the product, and /help lands there too.

CreatorStudio — design the announcements

Assistant — describe it, don't build it

In the capture: the Assistant's entry screen — four worked example prompts ("Play a chime when the doors open, and say 'stand clear of the doors' as they close", "Warn passengers 200 metres before their stop, and only after 22:00"…), a free-text box, and the promise printed right under it: "Nothing changes until you review and apply."

Describe what passengers should hear — "announce the next stop inside the bus, and the route and destination outside" — and the assistant proposes the playlists and triggers that produce it: the wording, the variables, the output channel, the thresholds, and a custom rule when the request isn't a journey moment ("only after 22:00").

Nothing changes until you say so. Every proposal is itemised on a review card — what it would create, what it would switch on, and what it would replace — each item can be unticked, and applying the whole plan is a single undo. The model never writes the config: its answer is rebuilt field by field against the real catalogue first, so an invented trigger type, a fact the vehicle feed doesn't carry, or a {variable} the engine can't resolve is dropped and reported rather than published.

It runs on your own machines. The assistant asks the portal first, which talks to any OpenAI-compatible model — a local Ollama or LM Studio, or a hosted provider if you prefer — so no announcement text has to leave the site and there is no per-call cost. The screen names the model that answered. With nothing configured it falls back to a cloud service, and then to a keyword draft marked Offline draft; the review-and-apply path is identical either way.

Playlist library

In the capture: the Baltimore project's full repertoire — 18 playlists, 16 of them interior (Approaching Stop, Arrived at Stop, Doors Open, Connection Info, Final Destination Announcement…), one exterior (Route to Destination) and one on both channels ("Bus not in service. New trip starting soon"), each row showing its language, voice, element count and last-edited date at a glance — and, in the left nav, the Audio sub-menu the playlist family lives under: Playlists, Voice, TTS suppliers, Pronunciation, Volume.

Every announcement is a playlist — an ordered list of spoken text, live variables, pauses and audio clips. They're grouped by where they play (interior / exterior / both) with language and element count at a glance. Create, duplicate or edit one inline; a worked-example library ships to copy from. Edits go live fleet-wide the moment you Publish — no redeploy.

Playlist editor

In the capture: the interior "Next Stop" playlist — speaker routing offered as Interior / Exterior / Both, one voice chosen for the whole playlist, an "Also speak in" picker ready to add a bilingual repeat, and a single static-text element "The next stop is {nextStop}." at 100 % volume with its own volume slider and an optional custom voice for just that line.

Build one announcement element by element: static text, dynamic variables ({nextStop}, {destination}, {connectingServices}…), pauses and pre-recorded clips. Set the voice per playlist — or per line — and the speaker routing. "Also speak in" repeats the whole announcement in a second language and voice for bilingual stops, and Preview auditions it through the real TTS voice.

Triggers — one unified list

In the capture: the whole rule set on one screen — All (39) = the 33 built-in transit triggers plus Baltimore's custom rules, filterable to Active (7) / Off (32) — Journey: Activated and Running, Doors Close, Time to Stop, the three distance thresholds, Approaching Last Stop, Detour, Onward Connections and Service Alerts among the rows, each with its playlist assignment and its LED SIGNS column, because audio and signs are parallel outputs of one event. "Assign default playlists" and "Assign default LED signs" wire the standard setup in one click each.

Built-in and custom triggers live in one list — 33 built-in transit triggers (approaching / arrived / departing a stop, doors, stop request, detour, disruption, last stop and more) and every custom rule beneath them, with Active / Off / All filter chips and a Geofences tab beside. Switch each on per service and map it to the playlist it should speak, with conditions (distance / time thresholds, speed, occupancy) and a priority. The engine fires them automatically from the live trip feed.

In the capture: "Arrived at Stop" opened in place — the AUDIO group (single playlist or an interior/exterior split, sequences and repeats), the PREREQUISITES gates (doors, speed), PRIORITY level 5 with interrupt / queue toggles, and the LED SIGNS group binding one template per face, previewed as live amber pixels: "20 CITY CENTRE" on front and side, the bare "20" on the rear.

Expanding a row reveals everything that trigger does: its audio (a single playlist, or split interior/exterior channels, each optionally a sequence with a repeat count), its prerequisite gates (door open/closed, stop button, speed window — the announcement is suppressed unless every set gate holds), its priority and interrupt/queue behaviour, and the LED layout per vehicle face for as long as it fires.

Custom (fact-based) triggers

In the capture: an Arriva rail rule built from raw PIS data — "2 min before next stop (fallback, no side/transfer data)": WHEN time to the next stop is above 0 s and at most 120 s AND the journey state is JOURNEY_RUNNING AND (in a nested NOT group) neither the exit side nor any onward connection is known — THEN play the basic two-minute announcement and wait 180 s before it may fire again, with the per-face SIGN bindings folded beneath.

When no built-in trigger fits, compose your own: a Scratch-style boolean expression (ALL / ANY / NOT) over 40 live journey facts — doors, speed, occupancy, connections, exit side, the stops ahead, the destination code the driver keyed in, traction-battery charge, even the engine clock and calendar. Try it feeds sample values and tells you whether it would fire. The very same evaluator then runs in the engine — and the same facts gate the LED sign cycles, so a rotation and an announcement are driven by one rule set.

In the capture: two Vilnius depot triggers built from raw PIS data — "Trip id matches pattern -[abc123]*d[123]*-" and its inverse — each also driving per-face LED layouts, previewed as live pixels: "20 GRĮŽTA Į PARKĄ" (returning to the depot) on one, "20 CITY CENTRE" on the other, with the "Try it" sample-value tester folded beneath.

Use case: a rail operator's announcement scheme, no code

In the capture: the Arriva tenant's live rule set — eight active triggers, all custom: "2 min before next stop" in a side-and-transfers-aware variant and a data-poor fallback, "2 min before the last stop" and "reached the last stop" each in exit-side/connections and basic variants, and "2 min before departure from the first stop" split by fast vs local train on the trip-id pattern — every one mapped to its own Arriva playlist.

The custom-trigger builder is expressive enough to carry a complete operator scheme: Arriva's train announcements are eight custom rules and zero code — each pair degrading gracefully from "exit side and onward connections known" to a fallback wording when the feed is thinner, and the welcome announcement choosing its phrasing by matching the trip id against fast-train patterns (snel|express|IC).

Geofence zones

In the capture: the Geofences tab beside the trigger list — two zones over the dark Baltimore map, a free-form purple polygon covering downtown and an amber circle to the north — named, colour-coded and listed on the left with edit / duplicate / delete actions, with "New circle" and "New polygon" ready, each zone usable as an "inside / outside" condition in any custom trigger.

Draw named zones on the map — circles or free-form polygons — and use "inside / outside this zone" as a condition in a custom trigger. Drag a corner to reshape, click an edge to add one. Announce a park-and-ride reminder inside a depot or a chime crossing a boundary — location-driven, no code.

LED Signs — layouts, displays & vehicles

Author the fleet's matrix signs alongside the spoken playlists. The LED Signs screen (/led-signs) is organised into tabs:

• Layout templates — reusable pixel canvases (presets by face — front / side / rear / interior). Create, duplicate or delete; each row shows a live thumbnail of the layout. The list is a full work surface: search by name, sign type or category, filter by panel size, usage or category, group by category (the default), sign type (catalog panel / face), market or usage, sort by name / size / elements / usage, fold groups away individually or all at once, and multi-select rows or whole groups for bulk duplicate / delete. Categories are the filing drawers. A config fills up fast — the standard family is seeded for every sign resolution, the via and main-stops seeders add one per size, presets and destination copies add more — so every template is filed: in the category its author gave it, or in the family its id says generated it (Standard sign layouts, Vilnius (Judu) sign set, Via destination, Main stops, Not in service, Destinations), and anything else under My templates. Existing configs therefore open already sorted, with nothing to migrate. Select any number of rows and Move them into a drawer — pick one in use or type a new name — or Unfile them again; it is one undo step. A template authored while a category filter is on is filed there, a copy keeps the drawer of the template it came from, and the layout editor carries the same Category field.
• Displays — cycle trees that pick a layout by trigger / journey state and rotate over time (the MatrixRenderer Display → Cycles → Layout contract). Same list controls: search, group by sign type or usage, sort, and bulk actions.
• Vehicles — the hardware roster: Ultima model picker, resolution, display type, position, FF address and colour mode; "Assign default templates" wires a standard setup in one click. A fleet carries many vehicle configurations and each one opened out is a page of its own, so the tab is a list: one row per vehicle — name, In use, sign count, the faces it covers, and a warning chip counting signs with no display bound (they show nothing) — and the full roster only for the rows you open. It opens on the vehicle in use; putting another one in use opens it too. Filter by name, position or resolution, and expand / collapse all.
• Vehicle faces — bind each physical sign to a Template display or to Announcement text (mirror what is spoken on the interior).
• Symbols — map a live value (e.g. line code) to a pictogram image on the sign.
• Route colours — the GTFS route_color / route_text_color per line, as a table the vehicle carries; full-colour panels honour it, single-colour panels ignore it, and a layout's own colour rule still wins so legibility is never overridden by branding.
• Abbreviations — text-fitting rules shared with the fit checker: whole-value or per-word replacements, optionally applied only when tight so the full text keeps appearing wherever it fits.

In the capture: 376 templates staying navigable — grouped by category with the Destinations and Main stops drawers open, every row carrying a live pixel thumbnail, its panel model (SS3-FF 16×120, Ultima 32×240…), an element count and where it is used, with search, filters and bulk selection above.

In the capture: the "Example vehicle (US)" roster, in use with six physical signs — Front, Front extra, Left, Right, Rear, Driver — each with its catalog panel, resolution, FF address and colour mode, and a live thumbnail of what that face renders right now: "20 CITY CENTRE" on the destination faces, the bare route number on the rear and driver panels. The three-step banner above spells out the model: a vehicle is its signs, each sign shows a display, a display picks templates.

In the capture: the abbreviation table that lets one text fit every panel — all twelve Baltimore CityLink brands mapped to two-letter codes (CityLink RED → RD, BLUE → BL…), each rule with its "when tight" switch. The full brand fits a 200-column front sign; its code fits the 40-column driver panel; the same rules feed the fit checker.

In the capture: value → pictogram mappings driven by the Vilnius feed — a destination containing "Oro uosta" (airport) wears the plane symbol, "Stotis" (station) the train, "apylanka" (detour) the diversion sign — with an upload slot beside the built-in set for a fleet's own artwork.

In the capture: the per-line colour table — red "ordinary city line" chips for lines 11, 1 and 5, the green express 3G, the blue-and-yellow night N9, and Baltimore's CityLink BLUE and RED — each with background / text / outline swatches and a live rendered chip, importable straight from GTFS.

Layouts and displays publish with the rest of the config; the engine rasterises them with the same Luminator FNT fonts the hardware ships and emits mono or RGB Mobitec FF frames — or Hanover HCPS/SuperX frames for signs rostered with the Hanover protocol (vendor-independent).

Destinations — the pre-programmed destination lists

Reached from LED → Destinations: the left nav nests it under LED (and /led-signs/destinations redirects there), because a destination is not a peer of the sign authoring — it is what those signs show for a code the driver enters. The LED Signs screen links across to it as well.

A destination is the code a driver keys in and the text every sign then shows. The PIS-PT feed selects one by number (pis/0/destination's number, optionally scoped to a line by externalDisplay.lineCode) — the standard says the number alone is the normal case, so without a stored list a code-only selection leaves the signs blank.

The Destinations screen (/destinations) holds those lists, and the editor is WYSIWYG — you type on the sign:

• Pick a code on the left; the vehicle-in-use's panel fills the editor, rendered by the same rasteriser the engine publishes with: the sign's real resolution, its FNT font, its colour mode, its symbols and abbreviation rules. Not a mock-up of the sign — the sign.
• Click any text on the panel and type. The editable areas are outlined and labelled (Destination, Row 2, Via, Line number…); the caret sits over the pixels and every keystroke re-renders them. Tab and Shift+Tab walk the fields, Enter keeps, Esc puts the value back. A newly added destination opens straight into typing. Areas the author cannot change — the template's own words, the live "Stopping at:" row, a value the template pins — say so instead of pretending to be editable.
• Which field sits behind which area is discovered by probing the template, so it works for plain {token} text, raw expressions and priority chains alike: on a destination that has a via, the via-priority area edits the via, because that is what the sign is showing.
• Arrange it freely. Drag any area to move it, pull its handles to resize, and use the toolbar to set horizontal and vertical alignment, the font size (Auto fits the biggest that will go — pinning a size is how two signs are made to match), what happens when the text is too long (scale / scroll / clip / wrap), the exact X / Y / W / H, the front-to-back order, or to remove it.
• All text settings opens the same inspector the template editor uses, on the selected area: content and {variables}, the raw expression, the text rules (letter case, show-only-part, rotate the parts of a value, symbol slot), the font ladder and character spacing, the scrolling switches and speed, alternations, blink, and the text / outline colours — plus the element type itself, which keeps the name and box it occupied. An area driven by a destination field says so, so its Content (the {token} that fetches the value) is never mistaken for the value: that is still typed on the sign. Because arranging already forks the template to this destination, none of it can disturb the others.
• Add text puts another line on the sign: a destination field, or static text you type in place. Add shape draws a line, box or circle — separators, frames and highlights, with a thickness and a solid/outline switch. Add symbol offers the built-in public-transport pictograms — accessibility (wheelchair, priority seat, pram), on-board facilities (bicycles, Wi-Fi, air conditioning, power, toilet, luggage, CCTV), vehicle modes (bus, school bus, rail replacement bus, tram, train, metro, ferry), wayfinding (arrows, Park & Ride, exit, lift, stop requested) and notices (no smoking, no entry, info, warning, time, ticket, tick, cross). Add image places your own PNG. Everything lands where there is room and is then dragged and sized like anything else.
• A pictogram per panel height. The picker has a size switch — this sign, or 8 / 12 / 16 / 24 px — and each height is a separately drawn glyph, previewed exactly as the panel will show it. A curve rasterised down to 12 pixels is a smudge, so the sizes a fleet actually runs are drawn by hand and the shapes only take over on panels no hand-drawn size fits (roughly 20 px and up, where they are honest). The engine draws from the same definitions, so the sign and the preview agree.
• Arranging gives that destination its own copy of the template, bound to that sign, and says so: every other destination keeps the shared one. Use the shared template puts it back.
• Fit is checked as you type: an area whose text no longer fits turns red with the exact pixels it needs versus what it has, and the sign tabs carry a badge — so a name that fits the front but not the rear is caught at the keyboard, not on the street.
• Characters the sign font cannot draw are named, not silently changed. The Luminator FNT set is latin-1 (ANSI, dfCharSet 0) and its substitution glyph is @, so Lithuanian, Latvian, Polish and Czech letters have no artwork: Zuikių g. reached the panel as Zuiki@ g., and the files' blank placeholder cells punched 25px holes into words. The renderer now falls back to the base letter (ų → u, ž → z, ė → e) — measuring and rasterising fold identically, so nothing shifts — and the fit check reports the substitution on the element ("ų → u"), in the editor and in Check fit. Only a character with no latin base at all still shows the font's @. Proper diacritics would need Baltic / Central-European FNT files from Luminator; nothing else in the pipeline is in the way.
• Switch panels with the sign tabs, or glance at On the other signs below to see the same destination on every face at once. Zoom is 2×–8×.
• Code, line code and out-of-service sit beside the panel; rows, symbols, notes and an optional template per sign for one destination live under More. Duplicate codes are flagged — only the first would ever be reachable.
• Check fit runs the whole list through the vehicle's templates in one pass, with the same report (and one-click abbreviations) the LED Signs screen uses.
• Review sheet (/destinations/review/:id) — a printable page of every code, its text and its rendered signs, with an approval block: Print → Save as PDF, or send it for sign-off.

In the capture: the "Vilnius (Judu) destinations" list in use, code 5 — Fabijoniškės on line 3G — open in the editor. The panel renders "3G Fabijoniskes" as live amber pixels with the honest warning that the latin-1 sign font draws š and ė as their base letters; four of the six sign tabs carry red fit badges, and "On the other signs" shows the same code on every face at once — including the Right panel clipping to "abijoniskes", exactly the problem the badges flag, and the green route-colour flag on the full-colour front-extra panel.

In the capture: the built-in pictogram library opened from the editor — accessibility, on-board, vehicle, wayfinding and notice symbols, each previewed as real LED dots, with the size switch (8 / 12 / 16 / 24 px) choosing between separately hand-drawn glyphs, so what the picker shows at 16 px is pixel-for-pixel what a 16-px panel will display.

The list in use publishes with the rest of the config; the engine resolves an incoming code through it. Each list has a Priority setting (control bar on the Destinations screen) that decides how a matched code applies against the live feed:

• Signs win, feed for speech (default) — the stored text takes priority on the SIGNS; spoken announcements follow the live feed (using the stored name only when the feed sends none, so a code-only journey still speaks a destination).
• Signs & speech win — the stored text takes priority on both the signs and the announcements.
• Feed always wins — the live feed always wins; the stored list is only a lookup fallback for what the feed doesn't send.

A partial entry only overrides the fields it defines; a code with no list match leaves the live feed untouched, whatever the priority. The destination code and the line code are also trigger facts, so a custom trigger can fire on a specific pre-programmed destination. The Live Fleet Dashboard → Monitor → Displays drawer shows the current Destination code and whether it resolved to a pre-programmed entry (which then takes priority) or falls through to the live feed. With DESTINATION_LIST_PUBLISH=true the engine also publishes the list itself on pis/0/list/destinations so a driver console can offer the codes — off by default, since a real PIS system may own that topic.

Layout editor

In the capture: the 200×24 "Destination + Main stops" template at 6× zoom — the Destination element selected on the canvas with its inspector open (exact X/Y/W/H, content "{destinationMain}", an expression override, letter-case and symbol-slot rules) while the live-preview strip below renders the very frame the sign would show for the sample journey state.

A visual pixel editor for one layout: drag and resize Text, Image and Rectangle elements on a canvas that matches the sign resolution. Set overflow (Clip / Scale / Wrap / Scroll / WrapScale), FNT font ladder, alignment, scroll, alternation, blink and colours. Drop in the same live variables the audio playlists use ({nextStop}, {destination}, {lineCode}…) or a textExpression over globalState. Colour rules restyle the whole face when a field matches a value. Sample journey state drives an amber / RGB preview so what you see is what the bus shows.

Display editor

In the capture: a display's three cycles — Not in service, Via destination, Main stops — each with a visual trigger ("Vehicle is not in service", "Destination has a 'via'") and, beneath it, the raw expression it compiles to; the Main stops cycle rotates two layouts on a 10 s / 5 s beat, and the live preview renders the winning layout ("20 CITY CENTRE") for the editable sample state.

Compose the cycle tree for one display: ordered cycles, each with a visual trigger condition (the same Scratch-style builder as custom triggers) that compiles to an enabledExpression, and timed rotations that point at a layoutId for a duration. A live preview shows which layout wins for the current sample state — the same resolver the engine uses at runtime.

Triggers → LED faces

On both the built-in trigger matrix and custom triggers, bind a layout per vehicle face (front / side / rear / interior) for as long as that trigger is firing. Audio playlist and LED override are parallel outputs of the same event — speak "Next stop Central" and show a dedicated destination layout at the same moment. "Assign default LED signs" fills the usual in-service / not-in-service defaults.

Route simulator

In the capture: Baltimore route 26 (Patapsco Station – Mondawmin), the 04:59 PATAPSCO LR trip with its 52 stops, mid-replay — the vehicle-in-use's LED faces rendering live per position ("26 PATAPSCO LR", the front-extra panel scrolling "Stopping at: Mond…"), door / stop-request / journey-state override controls, the event timeline auditioning each spoken line at Mondawmin Metro Station and PULASKI ST & BRYANT AVE with interior / exterior badges, and the full trip traced on the map.

Replay a real GTFS trip stop by stop and see exactly what would be spoken and shown on the LED signs at each event — before anything reaches a vehicle. The timeline models trip-start, approaching / arrived / departing, doors and stop-request (custom triggers interleaved); each row auditions through the real TTS and previews the active matrix layouts. Catch a silent stop, a wrong variable or a blank face on the bench.

Pronunciation lexicon

In the capture: the 69-entry lexicon with the clickable IPA phoneme palette and Import GTFS above, GTFS-imported expansions (ENT → "Ear Nose and Throat", EXPY → "Expressway", FS → "Far Side", GBMC → "Greater Baltimore Medical Center") each with a play button, an approval mark and a blue GTFS source chip — and below, the pre-recorded stop-names section with its bulk MP3 import, where voice-talent clips replace TTS per stop.

Fix how the voice says things: plain respellings ("AVE" → "Avenue") or IPA phonemes, optionally per language. Import stop and route names straight from GTFS and let AI expand the abbreviations — so "AACC" comes out "Anne Arundel Community College", not letter by letter. Applied everywhere the engine speaks.

The Audio sub-menu — voice, suppliers, pronunciation, volume

The audio family lives under Audio in the left nav — the voice is the audio output, not a setting, so it sits beside the playlists it speaks rather than behind a settings cog:

The old /settings/… deep links still redirect to their new homes. Settings proper (below) keeps only what is genuinely project-plumbing: timezone, the GTFS feed, and the configuration file. The toolbar keeps the actions — undo/redo, import/export and Publish.

In the capture: Audio ▸ Voice — English (US), voice Micah22k_NV at 1.00×, the one-click "All playlists use this voice" already confirmed ("All 18 playlists use Micah22k_NV"), and the "Which supplier speaks it" card linking across to TTS suppliers — with the reminder that voice changes reach the engine only on Publish.

In the capture: Audio ▸ Volume — the default volume at 80% and one rule live: "Night quiet hours", dropping announcements to 60% between 22:00 and 06:00. A rule combines any of time of day, weekdays, route, stop and geofence (all its conditions must hold; the most specific matching rule wins) — routes and stops picked from the imported GTFS feed, geofences from the circle/polygon zones drawn on the Triggers map. One-click examples ("Weekday rush boost", "Quiet zone") seed common rules.

Voices & TTS suppliers (Audio ▸ TTS suppliers)

In the capture: the supplier bench with the same line ("The next stop is Central Station.") ready to play through every card — twelve suppliers on screen: Acapela configured and selected as the engine supplier with voice Dimitris22k_NV, Azure Speech and ElevenLabs beside it, Google Cloud TTS / Amazon Polly / ReadSpeaker awaiting credentials with their market-scorecard ranks showing, the self-hosted Kokoro, Piper and eSpeak NG cards, and the endpoint-based Cerence, CereProc and Picovoice Orca — each with Play, "Use for engine" and "Failover" actions.

Play one line through every supplier — 13 of them: Azure Speech, ElevenLabs, Acapela, Google Cloud TTS, Amazon Polly, ReadSpeaker, the self-hosted Kokoro / Piper / eSpeak NG, the endpoint-based Cerence / CereProc / Picovoice Orca, and a silent mock — back to back, and pick which the engine renders with — and which voice that supplier speaks with. Both choices go live on Publish. The picked voice replaces the engine's env default (AZURE_SPEECH_VOICE and friends), so it is what every playlist left on "provider default" says. The A/B comparison uses the engine's real clients, so what you hear is what the fleet gets. Each supplier card shows capability badges — SSML lexicon, per-element volume, offline — straight from the engine's own capability descriptor, so what a supplier silently can't do (say, honour a per-line volume) is visible before it is picked, and the playlist editor repeats the warning next to any volume the active supplier would ignore. A second supplier can be marked as the failover: the engine renders through it while the primary's circuit breaker is open, so a vendor outage keeps announcements speaking (in the failover's voice) instead of degrading to the engine's fallback tone — and the dashboard's Health panel shows each supplier's synth count, mean latency and characters sent. (/voices and the old /settings/suppliers still work and land here.)

Settings — the project plumbing

In the capture: Settings — the timezone the calendar triggers run on (engine default / host local, with a live "Now in this zone" readout), the GTFS-feed slot that powers the Simulator and every stop picker (imported.zip · 65 routes · 13 733 trips · 3 963 stops), and the configuration-file card that makes the whole project one portable JSON.

Two file actions read alike and are not, so both say which is which: Import / Export (toolbar, and Settings → Configuration file) loads a file into the open project, replacing it; the project ⋮ → Import as a new project… leaves the open one untouched and creates a separate project.

Publish history & rollback

In the capture: ten versions of the project, v10 tagged LIVE (published 12 Aug, 12:02), every earlier row one click from Restore, with publisher, timestamp and playlist / trigger counts per version — running on the cloud deployment, where the config_versions table stores the trail durably.

Every publish is recorded — who published what, and when, with playlist and trigger counts. The current version is tagged LIVE; restore any earlier version in one click (it re-publishes as a new version, so nothing is ever lost). Sortable columns and a free-text filter (publisher, note, version) keep long audit trails navigable. Governance for a fleet that speaks to the public.

Engine dashboard — operate & audit

The dashboard is six menu entries, deliberately few: Monitor (the cockpit — map, feed and the displays/source drawer), Performance & Health, Proof of Play, History, Play on a device and Published config — a read-only view of what CreatorStudio last published, not a settings screen; the dashboard has none, because every project setting belongs to the Creator and the operational context (source mode, tenant, vehicle, TFT layout) belongs in the cockpit drawer next to what it affects. Screens that were once separate pages — Live, Map, LED Signs — are panels inside the cockpit now, because an operator watching a bus needs them at the same time, not in different tabs; their old links redirect. Documentation is not a dashboard tab either: it lives in the Documentation Center (/docs), reached from the suite rail that every app shares.

Live monitor cockpit

In the capture: live vehicle 13027 on Baltimore's route 22 to HOPKINS BAYVIEW, 27% through its 60-stop journey — current stop 40th St & Rotunda Mall Dr, next University Pkwy "arriving now" — with the Source drawer scoped to the baltimore-md-mta tenant (8 tenants on the broker, 3 077 vehicles on a journey, the bridge forwarding 167 msg/s), the raw Inbound PT-PIS feed streaming beneath the vehicle picker, and a header pill flagging 2 450 vehicles silent for more than five minutes.

The operator's cockpit for one vehicle, all on one screen: a heading-up map (the bus always points up) showing the journey, stops coloured by what happened at each, and where every announcement fired; a live feed (this vehicle's timeline, or the whole fleet — click a bus to follow it); and a drawer of tools — the raw PIS-PT signal table, one-click signal injection, and the LED-sign / TFT previews.

In the capture: the drawer's Triggers tab for the same vehicle — every fact the trigger evaluator sees, live, with its source topic (journey state, next stop 40th St & Rotunda Mall Dr, doors closed, speed 2 km/h), above the one-click injection buttons — stop request, doors open, off-route, crowded, alert, destination override, alarm — for exercising the engine without touching a bus.

In the capture: the right rail switched to the whole fleet — stop requests, arrivals and departures from vehicles across CityLink RED and BLUE and route 63 scrolling in one feed — while the Source drawer filters the 11 vehicles currently on a journey and offers to serve them all.

LED signs & TFT preview

In the capture: every surface of vehicle 13027 mid-journey on route 22 — the interior LED scrolling "NEXT STOP IS UNIVERS…", the exterior front / side / left / rear faces showing "22 HOPKINS BAYVIEW", and the 1920×610 interior TFT beneath on its published layout — all driven by one live journey state, while fleet vehicle cards (Departing / Arrived at Stop) stream in the right rail.

See what the passenger sees: the interior LED dot-matrix, the exterior front / side / rear destination signs, and the interior TFT — all rendered live from the engine's output using the same font the hardware ships, so the preview matches the bus exactly.

LED Signs (live matrix)

The cockpit's Displays drawer loads the published layouts / displays / vehicle roster and renders every face from live MQTT fleet state (or a sample journey). The same cycle + trigger-override pipeline the engine uses decides which layout is active; interior / announcement-mode faces mirror the spoken text. Reload from the running config, or jump to Creator when nothing is published yet. This was a page of its own (/signs) until it became clear it was a second view of what the cockpit already shows — the route now redirects to the cockpit.

Performance & timing

(Performance and Health share one menu entry, switched by a segmented control — they are two reads of the same live engine beat.)

In the capture: a fully warmed cache — four live announcements (approaching / departing / arrived at stop), every one a cache hit: 3 ms average lead time end to end, 0 ms average TTS, 100% cache hit rate, the timing bars showing resolve / render / publish with no synth segment at all. The cold phrase is paid for once, then the whole fleet reuses it in single-digit milliseconds.

Per-announcement latency broken into resolve / render / TTS / publish, with the cache hit-rate. A cached phrase completes in about 2 ms; a cold synth ~1 s, then it's cached and reused fleet-wide. Prove the engine is fast — and see exactly where any slow announcement spent its time.

Health & telemetry

In the capture: one engine tracking 7 322 real vehicles at ~400 msg/s with 21 ms event-loop lag and 249 MB of memory — 8.4 trigger events/s derived from the stream, the upstream bridge at 158 forwarded messages/s (109 597 in total this session), and the rolling telemetry table underneath. The same numbers the load ladder measured, now on live traffic.

Live engine vitals — messages/s, events/s, event-loop lag, memory, cache hit-rate, in-flight / queued / dropped renders, synth-dedup — plus upstream-bridge throughput. Sparklines and a rolling table flag a stale or struggling engine at a glance.

Announcement history

In the capture: 48 records for vehicle 13027's route-22 run — every row showing the trigger (Approaching / Departing / Arrived at Stop), the stop, the announced text with its LED line, the language and voice, the interior output channel and the render time in milliseconds.

Its own menu entry beside Proof of Play: the durable trail of every announcement the engine has spoken, across restarts — vehicle, trigger, stop, transcript and the lexicon-applied spoken text, voice and language, volume and timing. Filter by vehicle / trigger / free text, auto-refresh, export CSV. Proof of Play answers what a passenger was proven to hear; History answers what the engine said — different questions, so they are no longer stacked behind one segmented control.

Proof of Play — the audit trail

In the capture: a live route-22 run under audit — the journey group (47 records, 11:51–12:03) expanded straight into its evidence: each record a rendered LED strip ("THE NEXT STOP IS…", "NOW ARRIVING AT…") with AUDIO / INTERIOR surface badges and its firing trigger per stop, under the group-by chips (journey / route / destination / date / hour / vehicle) and the CSV / JSON proof-pack export.

The durable, tamper-evident record of what was actually played and shown, where and when — grouped here by journey, each record with the LED transcript. This is the accessibility (ADA) compliance evidence: dispatched vs vehicle-confirmed played, exportable as a signed CSV / JSON proof pack.

Proof of Play — every record

In the capture: the same audit flattened to one row per record — all 47 of 47 for the HOPKINS BAYVIEW run, each carrying its time, vehicle, surfaces (AUDIO / INTERIOR), route → destination, the announced content, the stop, its GPS location and the firing trigger, under the filter bar with its tenant chip and the CSV / JSON export.

Proof of Play — on the map

In the capture: all 321 records as dots over the Baltimore map — the route corridors through downtown, out to Dundalk and Middle River, traced by time-ordered trail lines; every announcement of the afternoon verifiable by the place it fired, one click from its transcript.

The same audit plotted geographically: a time-ordered trail of every announcement along the route (audio vs exterior-sign changes), each point clickable for its transcript and detail. Prove an announcement fired at the right place, not just at the right time.

Proof of Play — replay

In the capture: record 9 of 47 — vehicle 13027 on route 22 — re-rendered as the passenger experienced it: the interior LED scrolling "…T STOP IS LIBERTY HEIGH…", the front and side signs showing "22 HOPKINS BAYVIEW", and the spoken transcript beneath ("Next stop is LIBERTY HEIGHTS Avenue & DRUID PARK Drive Northbound"), with transport controls to step the journey frame by frame.

Step through a journey and re-show exactly what a passenger experienced — the interior LED, the exterior signs and the spoken transcript — reconstructed from the record, frame by frame. (The record is the proof; the replay re-voices it for review.)

Play on a device

In the capture: the QR code for vehicle 13027 ready to scan, with open-here and copy-link alternatives — and the "Before you blame the player" card that saves the first support call: tap Start once (browsers block audio until touched), check the iPhone silent switch, reach the broker's WebSocket port, turn the volume up.

Turn any phone, tablet or the onboard unit into a vehicle's speaker: scan the QR code and that device plays the vehicle's announcements the instant the engine speaks them — and reports back what actually played, closing the proof-of-play loop. No install.

Published config (triggers → playlists)

In the capture: 18 playlists and 33 triggers as the engine runs them — cards for Trip Start, Approaching / Arrived / Departing Stop, Doors Open (At Stop), Stop Request Button and Journey: Not In Traffic, each naming the playlist it speaks with every variable a distinct chip — read straight from the running process, with Import config and "Edit in CreatorStudio" beside the reload.

What the engine is executing right now, read straight from the running process: every trigger and the playlist(s) it speaks, with the templated text ({routeNumber}, {nextStop}, {connectingServices}…). The definitive "what will this bus say" view, plus a config import for offline setups.

On the vehicle

Passenger information app

In the capture: the boarding screen — type or scan a vehicle (here 13023), "Board this vehicle" or "Show this vehicle's LED signs", and the hand-off QR whose link carries the ids in the path (/player/v/baltimore-md-mta/13023), so it survives every camera app and proxy; the next-stop card waits for the journey.

In the capture: the boarded rider view on live CityLink LIME data — "This service to northwest hospital", current stop Saratoga St & Saint Paul St, 5 of 52 stops done — with the personal "getting off at" picker set to Edmondson Ave & Arlington Ave and its "11 stops until" alert banner counting down, and an "End & leave" control, all in a plain browser page.

The browser player doubles as a passenger information system: the live headsign (route → destination), current and next stop with an arrival countdown, journey progress, and a personalised "getting off at" stop picker that counts down and alerts you the moment your stop is next. It rides the vehicle's existing feed, speaks the announcements, keeps working offline, and needs no install.

LED signs on any screen

The player's LED half (/player/led) — like the standalone /sign and /vehicle pages — turns any browser into the vehicle's signs, rendered with the exact pixels the engine drives the hardware with.

In the capture: all six faces of live vehicle 24056 on one page — the amber front sign (route RD to UM MEDICAL CENTER over a scrolling stops line), the full-colour front-extra panel drawing the RD flag white-on-red, both side signs, and the rear and driver panels showing the bare route code — each at its true resolution with the real FNT fonts, each openable full-screen on its own display, with a kiosk view for the whole board.

CreatorStudio Suite — Product Requirements Document (PRD)

Document type: Product Requirements Document — as-built requirement specification · Status: v1.0 Date: 2026-08-12 · Owner: Product · Applies to: main @ 2f9798e

About this document

This PRD is the requirement specification for everything the CreatorStudio Suite has implemented. It was written from the shipped system: every requirement below is implemented and verified unless its row explicitly says otherwise. Use it to answer "what must the product do?" with the confidence that the answer is also "what the product does do, today".

It complements — and does not replace — its siblings:

Conventions. Shall = mandatory and implemented. Requirement IDs are PRD-<AREA>-<nn>. The Spec column cross-references the deeper acceptance criteria in FUNCTIONAL-SPEC.md (FR-…) where the baseline already covers the requirement; new marks capability shipped after that baseline (169 commits between the two documents — the deltas are called out throughout). Known deviations reference the spec's §10 defect register (D-nn).

1. Product overview

1.1 Problem

A transit vehicle must tell passengers where it is and what happens next — audibly (saloon speakers) and visually (interior scrolling sign, exterior destination signs) — in the passenger's language, automatically, without the driver touching anything, identically on every vehicle in the fleet. Under accessibility legislation (ADA and equivalents) the operator must also be able to prove afterwards that those announcements actually happened. Historically this content is baked into vehicle firmware: changing a phrase means a software release and a fleet-wide reflash.

1.2 The product

One sentence: a non-programmer authors what the fleet says and shows; the engine executes that content live against each vehicle's real-time trip feed — synthesising speech, rendering LED-sign graphics for multiple sign vendors, dispatching both back to the vehicle — and records durable, vehicle-confirmed evidence of what passengers actually heard and saw.

The suite is five deliverables behind one portal (:8080):

1.3 Product goals

1.4 Users

1.5 Scope

In scope: authoring; publication and config lifecycle; trigger evaluation; speech synthesis (13 suppliers); interior/exterior/matrix-template sign rendering (FF + Hanover); dispatch and priority arbitration; onboard playback and clip caching; proof-of-play capture, reporting and durable persistence; fleet monitoring and diagnostics; deployment back-office, on-vehicle and offline-bundle.

Out of scope (deliberately): vehicle hardware and wiring; the upstream trip-data system (PIS-PT/GTFS-RT is consumed, not produced); driver-facing UI; passenger mobile apps; ticketing.

2. Functional requirements

2.1 PRD-PRT — Portal, suite UX and documentation

2.2 PRD-PRJ — Projects, tenancy and configuration lifecycle

2.3 PRD-CNT — Content: playlists and elements

2.4 PRD-TRG — Triggers and rules

2.5 PRD-LEX — Pronunciation

2.6 PRD-VOX — Speech synthesis and suppliers

2.7 PRD-REN — Rendering, caching and pre-delivery

2.8 PRD-LED — LED signage (vendor-independent)

2.9 PRD-DSP — Dispatch and arbitration

2.10 PRD-PLY — Onboard playback

2.11 PRD-AUD — Proof of play, evidence and compliance

2.12 PRD-OPS — Operations, monitoring and diagnostics

2.13 PRD-DEP — Deployment and environments

2.14 PRD-SEC — Security

3. Non-functional requirements

Values marked [M] are measured, not estimated (see TEST-REPORT.md / SCALING.md).

4. External interfaces (summary)

MQTT — the primary integration contract (full payload contracts in docs/mqtt-specification.md): inbound PIS-PT on {tenant}/{vehicleId}/pis/0/#; outbound …/tts (ADT 4.x), …/tts/cache (pre-push), …/display, …/display/exterior (+ /ff, /hanover, and per-address variants of every raw path), …/display/signs[/…] (matrix templates), …/list/destinations; control engine/control/select + engine/control/tenant; telemetry engine/health, engine/metrics, engine/fleet, engine/bridge; acks on engine/played.

HTTP (portal :8080) — apps at /, /monitor/, /creator/, /player, /docs (+ the showcase decks and /build-stats); sign clients at /sign, /vehicle, /signs, /player/led; APIs: /config (GET/POST), /api/projects, /api/publish, /api/engine-config, /api/config-versions, /api/gtfs/expand, /history (filters/groupBy/CSV), /proof/report, /led-font.json, /tts-providers · /tts-voices · /tts-preview · /tts-briefing · /tts-scorecard.xlsx, /ai/assistant, /gtfs/*, /export/bundle, /diag, /broker, /mqtt-proxy (WS relay), /player/stream (SSE) · /player/ack · /player/qr.svg. Mutating or cost-bearing routes are token-gated (PRD-SEC-01); responses gzip; upload caps enforced.

External services — MQTT broker(s) (local + Luminator suite upstream); Azure AI Speech and the other 12 TTS suppliers; Azure PostgreSQL; Azure Blob Storage.

5. Verification and traceability

Verification gaps (unchanged from the baseline): no automated end-to-end run of the Go/Python players against a broker; FF/Hanover frames never driven into physical signs; report integrity hash tested at unit level only.

6. Known gaps and exclusions

The authoritative register is FUNCTIONAL-SPEC.md §10. Still-open items, summarised:

• Transport hardening (D-16/17 — wss, credentials, ACLs, QoS-≥1 acks) is deferred to Luminator Suite integration and blocks real-vehicle evidentiary use of proof-of-play.
• Exterior loudspeaker is not driven by any player (needs unit-specific amplifier enablement).
• requiresDirection gate and bus-type trigger await upstream feed signals.
• Custom triggers bypass the universal gates/settle/debounce (D-13).
• Audio ducking/cross-fade on interrupt; ffmpeg-gapless MP3 concatenation; multi-clip audio[] handling in players — accepted gaps.
• Geofence entering/leaving collapse to within/outside semantics (D-05).
• Creator sign-in awaits a suite identity provider; until then publish identity rows are honestly marked unverified.

CreatorStudio Suite — System Functional Description

Document type: System Functional Description (SFD) · Status: Baseline v1.0 · Date: 2026-07-14 Owner: System Design & Product · Applies to: feature/polygon-edit @ 4c3ee35

About this document

This is the functional specification: what the system does, for whom, and how you would know it worked. It is deliberately distinct from its two siblings:

Requirements are numbered (FR-xxx-nn) and carry acceptance criteria so they can be traced to tests. Behaviour described here was read from the code, not inherited from prior documentation; where the code and the existing documentation disagree, the code wins and the discrepancy is recorded in §10 Defect & Gap Register.

Reader's guide

1. Purpose, scope and business objective

1.1 The problem

A transit vehicle must tell passengers where it is and what happens next — audibly (saloon speakers) and visually (interior scrolling sign, exterior destination signs) — in the passenger's language, automatically, without the driver touching anything, and identically on every vehicle in the fleet. Under accessibility legislation (ADA and equivalents) the operator must also be able to prove, after the fact, that those announcements actually happened.

Historically this content is baked into vehicle firmware: changing a phrase means a software release and a fleet-wide reflash.

1.2 What this system does

In one sentence: it lets a non-programmer author what the fleet says, then executes that authored content live against each vehicle's real-time trip feed — synthesising speech, rendering sign graphics, dispatching both back to the vehicle, and recording durable evidence of what the passenger actually heard.

1.3 Business objectives

1.4 Scope

In scope: authoring; publication; trigger evaluation; speech synthesis; interior and exterior sign rendering; dispatch and priority arbitration; onboard playback; proof-of-play capture and reporting; fleet monitoring.

Out of scope (deliberately): vehicle hardware and wiring; the upstream trip-data system (PIS-PT is consumed, not produced); driver-facing UI; passenger mobile apps; ticketing.

2. Actors and stakeholders

3. Functional decomposition

The system is eight functional blocks across three planes. Each block is independently testable and communicates only over the published interfaces (§7).

4. Operational concept — primary use cases

UC-1 — Author and publish an announcement (FB-1 → FB-3)

An author selects a project, creates a playlist ("Next stop {nextStop}"), picks a voice, assigns it to the approaching-stop trigger, previews it through the real TTS supplier, resolves any lint findings, and clicks Publish. Within ~1 second every vehicle on that fleet begins using the new wording. No redeploy, no vehicle touch.

UC-2 — Announce a stop (FB-4 → FB-7)

The vehicle's feed reports progress to the next stop. The engine detects the transition, confirms the trigger's conditions and prerequisite gates hold, renders the playlist (cache hit ≈ 2 ms), publishes an ADT audio payload plus an interior LED bitmap, the onboard player plays it, and — when the clip finishes — acknowledges playback. The record becomes evidence.

UC-3 — Interrupt for an emergency (FB-5, FB-7)

An alarm fires (priority 11) while an ambient announcement (priority 5) is mid-render. The scheduler interrupts: it aborts the superseded render so its audio is never published, and plays the alarm. Neither talks over the other.

UC-4 — Prove compliance for an audit period (FB-8)

A compliance officer scopes a route and date range and generates a certified coverage report: dispatched vs confirmed-played, per route/vehicle/day, an itemised exception list, an operator sign-off block, and a SHA-256 integrity hash. With GTFS enabled the report additionally reports stops that were never attempted — which dispatch-based coverage alone cannot detect.

UC-5 — Scope the fleet safely (FB-8 → FB-5)

The engine defaults to RENDER_SCOPE=selection: it announces nothing until an operator explicitly opts vehicles into the served set. This makes "connect to production and accidentally talk to 2000 buses" impossible by default.

UC-6 — Roll back a bad publish (FB-3)

An author publishes wording that reads badly on air. From History they restore an earlier version in one click; it is re-published as a new version — the audit trail is append-only and nothing is rewritten.

5. Functional requirements

Convention: shall = mandatory, implemented. Each requirement carries an acceptance criterion (AC). Requirements marked ⚠ have a known deviation recorded in §10.

5.1 FR-CFG — Configuration authoring and lifecycle

5.2 FR-CNT — Content (what is said)

5.3 FR-TRG — Rules (when it is said)

5.3.1 Built-in trigger set (33)

MQTT-driven set = 30. Custom triggers fire as a 31st event kind outside this taxonomy.

5.3.2 Condition catalogue

Prerequisite gates (authored per trigger under Prerequisites; universal, and they fail closed — a gate whose signal is absent blocks the announcement): requiresDoorOpen, requiresDoorClosed, requiresStopButtonPressed, requiresVelocityBelow, requiresVelocityAbove (both in speedUnit). The engine also declares requiresDirection, not enforced — no forward/reverse signal in the feed and deliberately not authorable (D-04).

5.3.3 Custom-trigger fact catalogue (40)

The same catalogue feeds the LED templates: a cycle's visual condition compiles to an expression over globalState.<factId>, so a sign rotation and an announcement are gated by the same facts.

Operators by type — boolean: isTrue, isFalse, changed · number: lt, lte, gt, gte, eq, ne, changed · enum: eq, ne, changed · string: eq, ne, contains, isEmpty, isNotEmpty, changed.

5.4 FR-REN — Realisation (audio and signage)

5.4.1 FR-LED — Matrix LED templates (Luminator MatrixRenderer)

Authors design destination and interior signs as first-class content — the same Display → Cycles → Layout → Elements contract as LuminatorSuite.Unit.MatrixRenderer.Api — and bind them to vehicle faces and triggers. Audio playlists and LED templates are parallel outputs of the same publish / trigger pipeline.

5.5 FR-DSP — Dispatch and arbitration

5.6 FR-PLY — Onboard playback

5.7 FR-AUD — Evidence and compliance

5.8 FR-OPS — Operations and monitoring

6. Data model — key entities

6.1 Authoring entities

6.2 Runtime entities

6.3 Evidence entities (HistoryRecord / proof_of_play)

at · type (audio|exterior|played) · traceId · tenant · vehicleId · vehicleKey · lat · lon · kind · triggerType · stopName · transcript · spoken · language · voice · outputType · volume · playlists[] · reps · bytes · totalMs · ttsMs · cacheHits · cacheMisses · unresolved · displayed · displayScroll · route · destination · journeyRef · faces[] (exterior) · playStatus (played) · dispatchedAt (played)

6.4 Persistence

Direction matters. projects is the input, engine_config the output, the file the fallback. Writing to engine_config does not change what the author sees — it is overwritten by the next publish. To change what an author sees, write the project.

7. External interfaces

7.1 MQTT — the primary integration contract

Inbound PIS-PT sub-topics consumed: journey, destination, destination/override, list/stops, linkprogress, stopinfo, journeystate, sensors/door, sensors/stop_button, vehicle/gnss_location, vehicle/exit_sides, connections, passenger_load, alarm_activation, shape.

7.2 HTTP — portal server (:8080)

Mutating or cost-bearing routes (POST /config, /tts-preview, /gtfs/import, /player/ack) require Authorization: Bearer $DASHBOARD_TOKEN when that variable is set (constant-time compare); reads are open.

7.3 External services

8. Non-functional requirements

Values marked [M] are measured, not estimated.

9. Verification and traceability

Verification gaps: no automated test drives the Go/Python players end-to-end against a broker; the FF hardware scroll frames are pinned byte-for-byte against the spec but have never been driven into a real sign; report integrity hashing is tested only at unit level.

10. Defect and gap register

The register is the product backlog's input. Severity is functional impact, not code quality.

10.1 Authored-but-inert — the author can configure something that does nothing

These are the highest-value findings: the UI implies a capability the runtime does not deliver, silently.

10.2 Capability regressions in the Angular Creator

The Angular Creator replaced the React app but does not yet expose everything the engine supports. Configs round-trip these fields safely (they survive import/export), but there is no UI to set them.

Mitigation today: custom (fact-based) triggers can express most gate logic, since the facts include doorOpen, stopPressed and speedKmh. But custom triggers bypass the gates, the settle window and the debounce entirely (D-13) — so it is not a like-for-like substitute.

10.3 Correctness and semantics

10.4 Security and audit integrity

10.5 Functional gaps (known, accepted)

10.6 Documentation drift

11. Roadmap

Ordered by the register above, not by engineering convenience.

Now — trust and safety (blocks any real-vehicle deployment)

1. Secure the transport (D-16, D-17): wss:// + credentials on the broker; make played-acks reliable (QoS ≥1). Without this the proof-of-play trail is forgeable, which negates BO-3.
2. Rotate the Azure Speech key (D-18); purge the hardcoded broker password (D-19).
3. Fix the authored-but-inert set (D-01, D-02, D-03): either wire them up or remove them from the UI. Done — the authoring surfaces are gone or flagged. bus-type and the arrivals data still need upstream signals before they can do anything (items 10 below).
4. Fix the double-announce on the final stop (D-11). Done.

Next — close the authoring regression 5. Restore prerequisite-gate authoring in the Creator (D-07) — the engine's headline safety gating is currently unreachable from the UI. Done. 6. Sequence / repetition / split-playlist authoring (D-08). Done. 7. Per-user identity on publish and proof (D-20). Publish half done: identity is verified server-side when a token is present and every row says whether it was. What remains is an identity source — either the suite hands the Creator a signed-in user's token, or the Creator grows its own login (who provisions accounts is the open question). Proof-of-play records are untouched by this.

Then — completeness 8. FF hardware scroll (D-22) — verify the interior frames on a bench sign, then extend to the exterior destination sub-region. 9. Exterior-speaker enablement (D-21) — needs vehicle integration. 10. bus-type and stationary arrivals — once the feed exposes formation/type and real-time arrivals. 11. Per-tenant proof retention/rotation.

Scale (not required for 2000) 12. TTS throughput tier (the remaining real wall: Azure F0 caps ~20 req/s). 13. engine/fleet decimation (D-28); paced retained-topic backfill (D-29). 14. Horizontal sharding / Redis-backed state for headroom and availability beyond ~3000. 15. ffmpeg gapless concatenation (D-24).

Housekeeping 16. Reconcile ARCHITECTURE.md with the current system (D-30). Done (2026-07-24) — every document re-checked against the code; the remaining sliver is D-31 (authoring-side tables).

12. Glossary

CreatorStudio — Architecture & System Documentation

This repo holds the CreatorStudio suite — two apps that make up one product:

• the CreatorStudio authoring app (web/creator/, Angular 20 + PrimeNG) where operators design announcements — organised into Projects (playlists, triggers, voices, lexicon), and
• the CreatorStudio Engine (src/, Node/TS) — an always-on backend that executes that config live, turning transit trip data into spoken passenger announcements and LED sign content for an entire fleet — plus the Angular dashboard (web/) to operate, monitor, and audit it.

The original React/Vite authoring app in audiocreator/ has been migrated to the Angular Creator at web/creator/ and is retired/vendored (no longer served — see §5). The database source of truth is db/migrations/ (plain SQL, applied by npm run db:migrate); its old Supabase backend (audiocreator/supabase/) was removed in the Azure migration.

All three are served together behind a single portal (scripts/dashboard-server.ts): / landing · /creator/ authoring app · /monitor/ dashboard (see §5). The engine is the primary subject of this document; the authoring app is covered where it drives the engine (config, trigger parity) and in §5.

This document is the single source of architectural truth for the project. Diagrams are Mermaid and render on GitHub and in the portal's Documentation Center (/docs → the consolidated handbook), which is where every document is published — the dashboard itself no longer carries a documentation panel.

About this document — who should read what

1. What it does (system function)

Modern transit vehicles must announce stops to passengers audibly (speakers) and visually (interior + exterior LED signs), in multiple languages, triggered automatically by where the bus is and what it is doing. Authoring that content (playlists, trigger rules, voices) is done in the CreatorStudio web app. This engine is the runtime that executes it live across the fleet.

In one sentence: it subscribes to each vehicle's live trip feed, decides what to say and show, synthesizes the audio, renders the sign graphics, and publishes them back to the vehicle — for hundreds of buses at once — while keeping a tamper-evident record of everything that played.

The authoring app and the dashboard are both in this repo (web/creator/ and web/) and served by the portal alongside the engine; the retired React original in audiocreator/ still deploys standalone to Lovable.

Value delivered

• Automated, consistent announcements — no driver action; every stop announced the same way.
• Multilingual — the same trigger speaks in the configured language with the right stop-name variant.
• Multi-surface — audio, interior scrolling sign, and front/side/rear destination signs stay in sync.
• Authored, not coded — operators change wording/voices/rules in CreatorStudio and publish live; the engine hot-swaps in ~1 s with no redeploy.
• Fleet-scale & cost-aware — identical phrases are synthesized once and reused across every bus.
• Auditable — a durable proof-of-play log records what was played/shown, where and when, for compliance and dispute resolution.

2. Tech stack

Backend runtime deps (package.json): mqtt, pg, dotenv, leaflet, marked, mermaid, jszip, qrcode-generator (the last four serve the portal: docs rendering, GTFS/zip import and the player QR code). Dev/tooling: typescript, tsx, aedes, ws, @types/ws, @types/node, concurrently, cross-env. Codebase: 75 backend modules (src/**/*.ts), 74 engine test files (671 tests), plus the Angular dashboard and Creator under web/ (72 spec files, 877 tests), and the retired/vendored React CreatorStudio app under audiocreator/ (its own package.json + Vitest suite). Full breakdown and coverage: TEST-REPORT.md.

3. Capabilities (feature map)

4. Backend architecture

4.1 System context

The engine and dashboard never call each other directly — MQTT topics + a small HTTP surface are the entire contract (see §7). The vehicle is no different: a player is just another MQTT client, so anything that can subscribe to a topic and decode an MP3 can be the speaker.

Note the loop is closed. The player publishes engine/played once a clip has finished, so the proof-of-play trail records what a passenger actually heard — not merely what the engine dispatched. That distinction is what an accessibility (ADA) audit asks for.

4.2 Module dependency map

4.3 Module responsibilities

4.4 External services

Corporate TLS: all Node processes run with --use-system-ca so HTTPS trusts the OS certificate store (required behind TLS-inspecting proxies).

5. Client architecture (web/ · clients/)

Everything downstream of the broker: the operator-facing apps (§5.1) and the vehicle players that actually make a sound (§5.2). Both are ordinary MQTT clients — neither has a private API into the engine.

5.1 Dashboard & Creator (web/)

Angular 20 standalone-component app: signals for state, hash routing, lazy-loaded routes (every panel is its own chunk; the cockpit and its Leaflet map are the heavy ones), esbuild bundle. It imports the engine's payload contracts directly from src/shared/payloads.ts via the @shared/* alias — producer and consumer share one type source — and the LED core from src/shared/led*.ts.

Six menu entries, each a route: Monitor · Performance & Health · Proof of Play · History · Play on a device · Config. Documentation is not one of them — it lives in the Documentation Center, reached from the suite rail.

Unified portal server (scripts/dashboard-server.ts) — a tiny no-framework server that serves both front-ends and the runtime data endpoints from one origin (no CORS/CDN), so the two apps appear as one product behind a landing-page menu:

Both apps are Angular projects in the web/ workspace, mounted purely at build time via each project's baseHref — so the server just maps a URL prefix to a dist dir with SPA fallback, no per-framework logic. Their API fetches are root-absolute and the dashboard's broker WebSocket targets …:9001, so both keep working under their prefixes; the Creator talks only to the portal's same-origin /api (projects, config publish, GTFS expand). Old /#/…, /ng/…, and the migration's temporary /creator-ng/… links redirect to their new homes. In dev, ng serve (npm run stack:dev) runs on :4200 and proxies data endpoints to :8080. The retired React CreatorStudio (audiocreator/) is still runnable standalone (npm run cs:dev on :8090, Lovable deploy) but is no longer served by the portal.

Suite navigation — both apps render a persistent 64px left rail (app switcher: brand → portal, Creator /creator/, Engine /monitor/, Player /player, and the Documentation Center /docs set apart at the foot as reference rather than an app; the current app is highlighted). The Angular Creator reuses the dashboard's web/src/app/suite-rail.component.ts directly. Both share the Figma/PrimeNG design system (§2), so the suite reads as one product. Documentation deliberately lives outside either app's own menu: one page publishes the handbook, the decks and the sources, and both apps link to it.

5.2 Vehicle players — the client side (clients/, /player)

The engine renders audio and publishes it; something on the vehicle has to play it. Three interchangeable clients do that, all speaking the same contract, so a fleet can mix them.

The contract — identical in all three:

subscribe   {tenant}/{vehicleId}/pis/0/tts   ADT 4.x — audio[0].content is base64 MP3 (or WAV)
publish     engine/played                    {traceId, tenant, vehicleId, playedAt, status}

Four behaviours matter and are deliberate:

• The ack is sent when the clip finishes, not when it arrives. That is what turns a dispatch log into proof of play (§1) — the difference an accessibility audit cares about.
• Clips are queued and played strictly one at a time. An announcement must never talk over the next one. (The dashboard's own auto-play is a monitor, not a vehicle, and does not queue.)
• Every received clip is cached on the vehicle under the payload's clipKey (a content hash the engine stamps on every message; repeats of an announcement share a key). A payload may then arrive key-only — audio[0] with no content — and the player replays the cached bytes: a few hundred bytes over the link instead of a few hundred kilobytes. Go/Python keep the cache on disk (CLIP_CACHE_DIR, LRU-bounded); the browser player uses IndexedDB. The closed-corpus pre-push (PREPUSH_ENABLED=true, §15) fills this cache ahead of need: cache-only clip deliveries arrive on …/tts/cache (kind: "clip-cache") — stored, never played, never acked.
• expiryDateTime is enforced. A clip past its expiry is dropped and acked expired, never played — a late "next stop Central" minutes after Central is worse than silence, and the proof trail must record the drop rather than a false play.

How audio reaches the loudspeaker (headless clients):

player → ffmpeg (decode MP3/WAV, apply speakers.INTERNAL volume) → aplay → ALSA
       → /dev/snd/pcmC0D0p → sound card → amplifier → loudspeaker

ffplay is deliberately not used, although it looks like the obvious choice: it needs SDL and is absent from Alpine's ffmpeg package, so a client that reaches for it silently falls back to a backend that cannot decode MP3 at all.

Deployment. Both headless clients ship as multi-arch Docker images (linux/amd64 + linux/arm64; the Go image cross-compiles rather than emulating, and its dependencies are vendored so the build is hermetic). A container has no sound card, so it needs --device /dev/snd — and the entrypoint joins the host's audio group by numeric gid, because it is 18 on Alpine but 29 on Debian/Raspberry Pi OS, and the kernel checks the number, not the name. Details: clients/README.md.

Not handled. The exterior loudspeaker. The payload carries speakers.EXTERNAL, but driving it on a real vehicle also means raising a digital output to enable that amplifier while the clip plays — unit-specific wiring (§7.1, on-vehicle integration), not implemented in these clients.

6. Software design

6.1 Core patterns

• MQTT topics as the API. The engine, dashboard, bridge, and vehicle units are fully decoupled; anything that speaks the topic contract can join. Enables simulation, multi-consumer, and language-agnostic integration.
• Multi-topic aggregation → edge-detected events. PIS-PT spreads trip state across many retained topics; VehicleContext merges them into one JourneyState, and PtTriggerEngine fires events only on meaningful transitions (debounced), not on every message.
• Pluggable TTS + resilience decorator. TtsProvider is one interface; ResilientTtsProvider wraps any provider with retry/backoff/circuit-breaker/fallback while preserving cache keys — and counts each supplier's synths/latency/characters for the per-provider health surface. While the primary's breaker is open, the switchable provider renders through a configured failover supplier (config.ttsFallbackProvider / TTS_FALLBACK_PROVIDER) — a vendor outage speaks in another vendor's voice instead of the fallback beep. The failover decision happens at pin() time, before the cache key is computed, so key and audio always belong to the same supplier.
• Layered, content-addressed cache. Cache key = hash of the exact synthesis inputs, so an identical phrase is generated once for the whole fleet and reused across memory → disk → Azure Blob. Pre-recorded clips share the same cache keyed by URL.
• Priority scheduler. One announcement plays per vehicle at a time; the scheduler enforces interrupt / queue / drop from authored (or tier-default) priority — safety announcements never wait behind ambient ones. Interrupting a still-rendering announcement aborts it (AbortSignal) so its audio is never published on top of the higher-priority one.
• Single source of truth for wire types. shared/payloads.ts is imported by both the engine and the Angular app; a contract change is a compile error on both sides.
• Deterministic sign rendering. The browser rasterizes signs with the same font the engine ships (/led-font.json), so previews and proof-of-play replays match the hardware exactly.

6.2 Configuration flow

CreatorStudio authors into a projects row (the source of truth for what the Creator lists); Publish to engine maps it (a no-op — the app already exports the engine's AnnouncementConfig shape) and upserts it to Postgres engine_config via the portal's POST /api/publish — one transaction with a monotonic config_versions row. A DB trigger fires pg_notify('engine_config_changed'); the engine's PgConfigSource reads that row and LISTENs, hot-swapping the fleet config in ~1 s (vehicles get the same effect from HttpConfigSource + the retained MQTT notify). The on-disk CONFIG_PATH is the offline fallback and is itself hot-reloaded.

The direction matters operationally: projects is the input, engine_config the output, and the file the fallback. Reads are remote-first, so a config written to the file is invisible while the live source is enabled, and a config written to engine_config does not change what the Creator lists — it is overwritten by the next publish. To change what an author sees, write the project.

An example of using that direction deliberately: the worked-example playlist library (config/announcement-config.sample.json) can be merged into any of the three targets without its triggers — scripts/lib/example-playlists.mjs appends the playlists and asserts triggers / customTriggers are byte-identical before writing. Since a Playlist carries no trigger field and the engine only ever walks trigger → playlist (§6.3), an unreferenced playlist is inert: authors get a library to copy from and the fleet says exactly what it said before.

6.3 Trigger → announcement decisioning

ptEngine fires an event only when (a) a state transition occurred, (b) the debounce elapsed, (c) the trigger's threshold condition matches (distance/time/geofence/speed/occupancy), and (d) its universal prerequisite gates hold (door/stop-button/velocity). pipeline then resolves interior/exterior/legacy playlists + sequences + repetitions, renders per-element (splitting TTS runs by voice/volume), applies volume adaptation, and routes to speakers via the ADT payload.

6.4 LED / sign rendering (for designers)

• Interior: 16 rows × 144 columns amber dot-matrix. Text centered when it fits, marked scroll when wider; the sign/dashboard pans a 144-wide window.
• Exterior: front (192) / side (160) / rear (48) px wide, 24 tall. A fixed route number (≤ 25 % of width, never scrolls) + destination that shrinks to fit, scrolling only as a last resort.
• FF/Mobitec: the same bitmap re-encoded as graphic-font-w column bytes (each byte = a 5-pixel vertical slice) inside an addressed 1463-L frame for RS-485 hardware.
• Hanover: the same bitmap again as a SuperX {\pic} vertical raster inside an addressed HCPS frame — sign-vendor independence: Luminator and Hanover panels show identical pixels from one render pass.

7. Interfaces & APIs

7.1 MQTT topic contract (primary integration surface)

Inbound PIS-PT sub-topics consumed: journey, destination, destination/override, list/stops, linkprogress, stopinfo, journeystate, sensors/door, sensors/stop_button, vehicle/gnss_location, vehicle/exit_sides, connections, passenger_load, alarm_activation, shape.

7.2 HTTP API (dashboard-server)

Auth. Every mutating or cost-bearing route (POST /config, /tts-preview, /gtfs/import, /player/ack, and the Creator API writes PUT/DELETE /api/projects, POST /api/publish, POST /api/gtfs/expand) is gated by authorized(): with DASHBOARD_TOKEN set it requires Authorization: Bearer … compared in constant time; unset (the lab default) leaves the portal open. Read routes are unauthenticated by design — the dashboard is an ops tool on a trusted network.

7.3 Config source (engine_config in Postgres)

One row per (tenant, fleet): tenant, fleet, config (jsonb — the AnnouncementConfig), schema_version, published_project_id (which project produced it; FK → projects, engine ignores it), updated_at. Keyed by a composite (tenant, fleet) primary key. Writes go through the portal's POST /api/publish (scripts/lib/creator-api.ts — one transaction: the engine_config upsert plus a monotonic config_versions row); a DB trigger fires pg_notify('engine_config_changed') on every insert/update. The engine reads with pg and LISTENs on that channel (PgConfigSource) — and when CONFIG_DB_TENANT_VALUE is set, filters to its own (tenant, fleet) row (empty = single-tenant). Vehicles, which cannot reach the database, use HttpConfigSource instead: GET {CONFIG_API_URL}/api/engine-config, re-fetched when the portal's retained MQTT notify (creatorstudio/{tenant}/{fleet}/config/updated) arrives. The whole schema lives in db/migrations/ (baseline 0001_baseline.sql, applied by npm run db:migrate), so the DB is reproducible from empty on any stock Postgres with no external dependency.

7.3a Projects & multitenancy (authoring side)

Authoring is organised into Projects (public.projects: id, tenant, fleet, name, description, config jsonb, timestamps) — named self-contained configs, one published per (tenant, fleet). Writes go through the portal's PUT / DELETE /api/projects (bearer-gated when DASHBOARD_TOKEN is set); reads are GET /api/projects?tenant=&fleet=. Every query is parameterized and tenant-scoped in the portal API — tenant is an explicit parameter today; deriving it from an authenticated session (Entra ID sign-in, verified published_by) is the documented follow-up (§12). The Creator's TenantService resolves the active tenant (?tenant= → window.__AUDIO_SUITE_TENANT__ → last used → default) and scopes every project read/write, so tenants are fully separated. Engine payload/MQTT/trigger contracts are unchanged by any of this.

7.3b AI authoring assistant (local-first)

The Creator's /assistant screen turns a plain-language description ("announce the next stop inside the bus, route + destination outside") into a plan of playlists and triggers. It asks two providers in order, so the feature degrades instead of disappearing:

So an on-prem install needs no cloud backend and no AI gateway: the portal already runs on the operator's machine and already holds the credentials, the Creator is served from the same origin (no CORS), and no announcement text leaves the site. The turn records which provider answered and the screen shows it, because a 7B local model and a hosted one write visibly different announcements.

The server half takes the same request and returns the plan at the top level. The client sends the catalogue of what may be built — trigger types, engine {variables}, the custom-trigger fact list, the project's existing playlists and geofences — because the Angular domain model is the single source of truth for it. The prompt itself lives once, in src/shared/assistantPrompt.ts — the portal imports it directly, so there is no carried copy to drift. Replies are parsed leniently — local models routinely wrap JSON in ``` fences or chat around it.

The model's answer is never trusted as config. web/creator/app/lib/assistant.ts rebuilds every field against the real model — unknown trigger type, a type the engine can never fire, a fact the PIS feed doesn't carry, an unresolvable {variable} (which would make the engine drop the whole announcement), an audio URL outside the preset list, an empty rule that would fire on every update — each is dropped and reported rather than applied. Nothing reaches the config until the author ticks it on the review card, and the whole plan lands as one undo entry (ConfigService.applyAssistantPlan). When the gateway is unreachable the same screen answers from a local keyword draft, marked Offline draft, through the identical validate → review → apply path.

7.4 Payload contracts

Defined once in src/shared/payloads.ts: ADTAudioPayload, ADTAudioItem, DisplayPayload, ExteriorPayload/ExteriorFace, MetricsPayload, HealthPayload. The ADT audio message conforms to the transHub ADT 4.x AsyncAPI spec.

8. Runtime sequence — signal to loudspeaker

The last three steps are the client side (§5.2), and they are what make the record admissible: up to publish …/tts the engine only knows what it sent.

9. Deployment & processes

• Engine — single long-running process (per-vehicle state in memory), one replica per inbound stream. Dockerfile builds it; runs with --use-system-ca. Waits for the broker (never crashes on a missing broker).
• Dashboard server — static file + data server (ops/monitoring); also serves the browser player.
• Vehicle player (§5.2) — one per vehicle, on the onboard unit, not in the back office. Go (single static binary) or Python; both as multi-arch images for x86-64 and ARM64 (docker buildx build --platform linux/amd64,linux/arm64). Needs --device /dev/snd to reach the speaker, and only outbound MQTT — no inbound ports, so it sits behind a vehicle's NAT unchanged. restart: unless-stopped and it reconnects on its own when the link drops.
• Broker — Mosquitto (prod) / aedes (dev); WebSocket listener required for the browser (dashboard and the /player page).
• Dev stacks (concurrently): stack:ui (broker+engine+dashboard), stack:live (adds the upstream bridge), stack:dev (broker+bridge+engine+dashboard+ng serve live-reload). Demos: proof:demo, ff:demo, led:demo, multi:demo, bridge:test, swedish, simulate, config:test, tts:test.
• Fully local backend (stock Postgres): db:start / db:stop start/remove a plain postgres:16 docker container; db:migrate applies db/migrations/ (the whole schema builds from empty — no cloud dependency); stack:local runs broker+bridge+engine+dashboard together with every process pointed at the local Postgres — it sets DATABASE_URL=postgres://postgres:postgres@127.0.0.1:5432/creatorstudio (and runs the migrations first), so a hosted database in .env is neither read nor written while it runs. Use stack:dev to keep the engine on the .env target. stack:vm is the deployed variant: same four processes, everything read from .env (the Azure pipeline runs db:migrate before starting it).

10. Performance

Latency budget (per announcement) — trigger fire → resolve → render (TTS) → publish. Measured on a live local run (Azure Speech, real journey):

Why it stays fast at scale

• Content-addressed dedup — a phrase like "Now arriving at Central Station" is synthesized once and reused by every bus on that route (observed: miss → cache 0/1, then cache 1/1 hits).
• Predictive pre-render warms the cache for upcoming stops, so most live announcements are hits.
• Ingest gating — trigger detection runs only on state-changing topics; high-frequency GNSS and the large static shape don't trigger work unless a speed/geofence trigger is enabled.
• Render backpressure — a global acquire/release counting semaphore bounds concurrent TTS renders (MAX_CONCURRENT_RENDERS); duplicate concurrent synths for the same phrase are collapsed by the cache's single-flight getOrSynth (surfaced as synthCoalesced in health).
• Bounded memory — LRU MP3 cache (TTS_MEM_CACHE_MAX) + on-disk FS cap (CACHE_MAX_FILES, oldest pruned by mtime) + idle VehicleContext eviction (CONTEXT_TTL_MS) keep RSS flat under fleet load.
• Health telemetry (engine/health) exposes msg/s, events/s, event-loop lag, RSS, cache hit-rate, in-flight, dropped, interrupted for live observation.

11. Scalability

• Multi-vehicle, opt-in by default. A single engine can serve many vehicles concurrently: per-vehicle contexts + trigger snapshots + scheduler slots, a global render semaphore (MAX_CONCURRENT_RENDERS) bounding total TTS concurrency, and per-vehicle serialization (one announcement per vehicle). Two render scopes:
  • RENDER_SCOPE=selection (default, production-safe) — the engine renders only the vehicles the dashboard opts in via engine/control/select (the served set). It serves nothing until an operator picks vehicles; an empty set = silent. Multi-select in the dashboard builds this set.
  • RENDER_SCOPE=all (load-test only) — serves every fully-tracked forwarded vehicle at once, ignoring the selection (discovery-only vehicles are still skipped). Only the exact literal all enables it; the dashboard surfaces a visible "ALL mode" warning when the engine reports this scope in its health beat. Verified with npm run multi:demo -- N (load-test/all) and npm run multi:demo -- N select (served-set/selection) — 10 selected of 15 driven, decoys stay silent, render concurrency bounded, fair (no starvation), zero cross-talk even when every phrase is a unique synth.
• Per-vehicle state is in memory → the natural horizontal unit is one engine replica per inbound stream / shard.
• Horizontal sharding — split the fleet by MQTT topic filter (e.g. per tenant or vehicle-id hash), one replica per shard; or externalize per-vehicle state to Redis to scale statelessly.
• Selection control channel — the dashboard can scope rendering to specific vehicles (engine/control/select) to bound TTS cost during operation/debugging.
• Cost scales with unique phrases, not vehicles — the shared cache plus single-flight getOrSynth (concurrent identical synths collapse to one) mean fleet growth adds near-zero TTS cost for repeated announcements.
• Broker is the throughput backbone; Mosquitto handles fleet-scale fan-in/out. Phase-0 hardening (bounded caches, eviction, ingest gating, backpressure, health metrics) lets one instance degrade gracefully; the full multi-vehicle / ~2000-bus plan is in SCALING.md.
• Lean upstream bridge. The bridge (scripts/bridge.ts) mirrors the live PIS feed to the local broker and is kept deliberately quiet: it follows the selection (full # only for served vehicles), keeps fleet discovery minimal (route+destination+phase only — list/stops and other heavy/high-rate topics are not bridged fleet-wide), tenant-scopes discovery (once a tenant is selected via engine/control/tenant it narrows from +/+/… to {tenant}/+/…, so it stops pulling the whole broker), and dedups byte-identical re-publishes so retained-value churn doesn't ripple through trigger detection and the dashboard. It publishes engine/bridge health (forwarded/s, deduped/s, bridged vehicles, upstream subs) which the dashboard surfaces. Verified with npm run bridge:test.

12. Security & operational concerns

• Secrets live in a gitignored .env (Azure key, upstream broker creds, DATABASE_URL, CACHE_BLOB_SAS_URL). No key of any kind ships in a browser bundle — the Creator talks same-origin to the portal, and every credential stays server-side.
• Database access: the Postgres server is private (VM allow-list / VNet, sslmode=require); browsers never reach it. All reads and writes go through the portal API, where every query is parameterized and tenant-scoped (tenant is an explicit request parameter today — deriving it from an authenticated session is the follow-up below).
• Publish identity — the Creator has no login; it forwards a host-shell-supplied token (SessionService) as the bearer when there is one, and config_versions.published_by_verified defaults false — the row is honestly marked unverified. The follow-up is Entra ID sign-in with a server-verified published_by; the seams (SessionService bearer, the published_by_verified column, the tenant columns) are already in place.
• Portal endpoints — the mutating / cost-bearing HTTP routes (config import, TTS preview, GTFS upload, played-ack, and the Creator API writes: project save/delete, publish, GTFS expand) are behind a constant-time Authorization: Bearer check when DASHBOARD_TOKEN is set; unset means an open lab portal, which is the default and must not be the deployed one.
• TLS inspection — --use-system-ca trusts the corporate root so HTTPS works behind proxies.
• Outstanding: the Azure Speech key was shared in plaintext during development and should be rotated in the Azure portal.
• Proof-of-play provides tamper-evident evidence (append-only log) for compliance/disputes.

13. Testing & quality

• 581 engine tests across 67 files (node --test, tsx) at 96.5 % line coverage, covering: trigger detection & prerequisite gates, custom fact triggers & geofence geometry, priority resolution & scheduling, the full matrix-LED pipeline (FNT parsing, layout render, cycles, colour rules, mono + RGB FF frames, browser↔engine parity), pre-programmed destination lists, project CRUD/migration/validation, ADT payload conformance, multilingual variable resolution, per-element voice/volume, SSML, TTS resilience & the three supplier HTTP clients, pre-recorded audio caching/retry, config env permutations + Postgres LISTEN reconnect, GTFS parsing & expected coverage, proof-of-play correlation/report/sink — plus two real-broker tests (aedes): a MqttBus round-trip and a full startEngine() boot.
• 758 front-end tests across 67 files (Vitest + jsdom via @angular/build:unit-test): every dashboard and Creator component rendered under TestBed, every service, and all pure logic.
• Exact per-suite counts, coverage and the full case catalog: TEST-REPORT.md.
• Trigger-parity guard (src/domain/triggerParity.ts) — a strict, bidirectional contract between the engine's trigger set and the CreatorStudio manifest (same types both ways, matching local flags, every MQTT trigger wired to an emitted event). Enforced by the manifestSync contract test AND npm run trigger:parity (which also accepts --file/--url to check a live/ freshly-exported manifest). This is what catches service-disruption-style drift automatically.
• Typecheck (tsc --noEmit) gates the shared contract across engine + Angular.
• End-to-end demos double as living verification: proof:demo, ff:demo, led:demo, swedish.
• CI (azure-pipelines.yml) runs typecheck + tests + the trigger-parity guard + the dashboard build on every PR/push to main, blocking merges on drift or a broken build.

14. Gaps & known limitations