Software team briefing

CreatorStudio Suite
What we build · How it works

Internal engineering overview: product scope, runtime architecture, module map, contracts, and where to change code. Not a sales deck.

Engine · Node/TS

Creator / Monitor · Angular 20

MQTT contract

Thin clients

What · product scope

One product, three runtime surfaces

Creator

web/creator/ — author playlists, triggers, voices, lexicon, LED layouts, publish to Azure PG.

Engine

src/ — always-on runtime: PIS-PT → triggers → TTS/cache → ADT + matrix/FF → proof.

Operate + clients

web/ monitor · public/player.html · clients/go · clients/python.

Portal (scripts/dashboard-server.ts) mounts Creator, Monitor, player, docs and decks on one origin.

What · capabilities

Feature map the engine must deliver

Capability	Contract / note	Primary code
Triggers	33 built-in + custom + geofence; edge-detect + gates	`pis/ptEngine.ts`
Playlist render	{vars} → MP3 + transcript; priority schedule	`engine/playlistRenderer.ts`
TTS + cache	Pluggable providers; LRU → FS → Azure Blob; single-flight	`tts/*`
Matrix LED	Display→Cycles→Layout; FNT; FF mono/RGB	`engine/matrix/`, `engine/ff/`
Config hot-swap	pg_notify/LISTEN ~1 s; file fallback	`config/pgConfigSource.ts`
Proof of play	Dispatched + `engine/played` ack	`engine/history.ts`

How · runtime path

Happy path for one announcement

PIS-PT→VehicleContext→PtTriggerEngine→ Pipeline→Render→MqttBus→Client ack

Ingest rules

Only state-changing signals wake triggers
GNSS firehose is gated
Per-vehicle context; render backpressure semaphore

Render rules

Cache key = hash(text + voice)
Prerender warms next stops
Same trigger can override LED face layouts

How · integration contract

MQTT topics are the API

Dir	Topic	Payload
IN	`{tenant}/{vehicleId}/pis/0/#`	Journey / sensors into engine
OUT	`…/pis/0/tts`	ADT 4.x — base64 audio, speakers, traceId
OUT	`…/display` · `…/exterior`	Interior / exterior bitmaps
OUT	`…/display/signs` · `…/**/ff`	Matrix frames + raw Mobitec FF
ACK	`engine/played`	Client confirms clip finished
OPS	`engine/fleet` · health · metrics	Dashboard retained views

Engine and dashboard never call each other privately — MQTT + a small HTTP surface only. Shared payload types: src/shared/payloads.ts.

How · stack & layout

Where code lives

Backend

Node ≥ 20 · TypeScript ESM · tsx / tsc
src/index.ts composition root
MQTT via mqtt/client.ts
Tests: 67 engine files / 581 cases · 66 front-end files / 755 cases

Frontends

Angular 20 + PrimeNG — Creator & Monitor
Shared Figma theme preset
Portal server: scripts/dashboard-server.ts
Thin clients: Go / Python / browser

External deps the engine trusts

MQTT broker · Azure PostgreSQL (config + pg_notify) + Blob cache · TTS suppliers (Azure / ElevenLabs / Acapela) · optional on-disk config fallback.

How · change safely

Engineering guardrails

Config

Never require redeploy for content. Publish path must keep ~1 s hot-swap. Keep file fallback working for edge.

Clients

Treat MQTT contract as public API. Prefer additive topic/payload changes. Ack path is required for proof.

TTS / LED

Cache keys and FF encoding are fleet-visible. Measure cache hit-rate before changing synth paths.

Docs of record

ARCHITECTURE.md — system truth
FUNCTIONAL-SPEC.md — FR list (incl. LED)
OVERVIEW.md — product narrative

Local entry points

Portal → Creator / Monitor / Player
PRESENTATION.html — stakeholder showcase
npm test / engine load scripts before fleet claims

How · team focus

Suggested workstreams

Platform

Engine hardening, multi-tenant process model
Cache economics & TTS resilience
Edge container parity with cloud

Experience

Creator LED / Matrix authoring UX
Monitor proof & live sign fidelity
Player / passenger app polish

Integration

Client SDKs (Go/Python) + sample vehicles
MatrixRenderer / Ultima face roster
Contract tests for ADT + FF topics

Quality

Expand trigger / matrix unit tests
Load: 2k veh baseline as regression gate
Keep docs regenerated via npm run docs

Summary for engineering

Author → Publish → Trigger → Render → Actuate → Ack

Build thin clients against MQTT. Keep content out of firmware. Prefer hot-swap over redeploy. Proof requires played-ack. Suite signs are first-class — Matrix/FF belongs in the same pipeline as audio.

ARCHITECTURE.md

src/

web/creator · web/monitor

clients/*