Shout

The apps, broker by broker

What each Shout app keeps in which broker, and why. From a poll on one State Broker topic to Shout Arena on all four brokers.

Each app below links to Shout: open it in two windows to watch the data move. Topics are written app:{id}, one instance each (How Shout is built).

App	Event	State	Wire	Relay
Shout Arena	✅	✅	✅	✅
Shout Chat	✅	✅
Shout Tier List		✅
Shout Quiz Desk		✅		✅
Shout Poll		✅
Shout Paint	✅	✅
Shout Scoreboard		✅
Shout Kanban	✅	✅
Shout Tabletop	✅	✅

Shout Arena#

Open. A live session: the audience sends questions, comments, raised hands and reactions from their phones; the hosts, at the Desk, choose what everyone sees on the Stage. Each broker does what it's for:

Broker	Topic	What
Event Broker	`arena:{id}:in:{n}`	the inbox: messages, knocks, hands. Seats may publish only, never read
Event Broker	`arena:{id}:desk`	the hosts' commands (show, bring on stage, give the floor…), a log every Desk replays
Event Broker	`arena:{id}:seat:{key}`	the hosts' private messages to one person, on a key only that person and the hosts know
State Broker	`arena:{id}:stage:{n}`	the Stage: visible messages, the spotlight, who has the floor and for how long
State Broker	`arena:{id}:seat:{key}`	one person's status: seated, in line, their place in the queue
Wire Broker	`arena:{id}:in`, `arena:{id}:stage`	presence and reactions: not worth keeping
Relay Broker	`arena:{id}:desk`	electing which Desk applies the commands when several hosts are in

Two ideas worth borrowing:

One writer, many readers. Several hosts append commands to one log; the Desk the Relay Broker made active applies them to the states everyone reads. If it leaves, the next Desk becomes active and replays the log (Relay Broker → Serving a topic).
Forward, don't grant. Being let in or given the floor gives a participant no new rights: the Desk copies what they send to the Stage. So taking it back is immediate.

Shout Chat#

Open. Rooms, messages, who's online and who's typing.

Event Broker room:{room}: one message event per message. The page shows it when it comes back from the broker, so every screen has the same order; the server reads the last 100 on load.
State Broker room:{room}: one key per open tab, { name, typing }, refreshed every 20 s. A 120 s retention cleans up tabs that vanished.

The chat tutorial builds the same design.

Shout Tier List#

Open. Drag items into tiers, together.

State Broker tierlist:{id}: one item:{id} per item, merged on drop; one drag:{id} while someone holds it, updated about 15 times a second and deleted on drop. Positions are "how things are now", so no Event Broker.

Shout Quiz Desk#

Open. A live quiz whose answer key never leaves the host's device.

Relay Broker quiz:{id}: the host's page serves the topic. Each answer is a request to it; the reply, to that player alone, only says "received". Nothing is stored.
State Broker quiz:{id}: current (the question, without its answer) and scores, written by the host's page, the scores only when it reveals the answer.

No server holds the answers, and no player can read anyone else's: the Relay Broker delivers each request to the server of the topic and each response to its requester only.

Shout Poll#

Open. A question and live votes, on one topic.

State Broker poll:{id}: meta (the question), and one vote:{voterId} per voter. Changing a vote overwrites the key; withdrawing deletes it. Each browser counts the votes itself.

Shout Paint#

Open. A shared canvas.

Event Broker paint:{id}: one stroke event per pen-up, and clear. The canvas is its history, replayed from the last clear.
State Broker paint:{id}: one cursor:{clientId} per person, with the stroke being drawn, updated about 15 times a second, so others see it before the pen lifts.

Shout Scoreboard#

Open. The smallest app: one state.

State Broker scoreboard:{id}: one board key. Each field edit is a merge, applied atomically by the broker. A display page subscribes and calls tell for the current value, with no server round trip.

Shout Kanban#

Open. A kanban board for meetings: backlog, columns, focus and planning poker. Its topic is still board.

State Broker board:{id}: one key per item; each change is a merge of only the fields that changed, text included as it's typed, so two people editing different fields never overwrite each other. Short-lived keys say who is dragging or editing what.
Event Broker board:{id}:chat and :activity: the chat and the "Ana moved X" feed.

The collaborative editing tutorial builds the same design.

Shout Tabletop#

Open. Chess, cards and ludo, with dice and a chat.

State Broker tabletop:{id}:{game}: the table, one merge per move.
Event Broker tabletop:{id}:{game} and :chat: the game's log and the chat. Dice are rolled by Shout's server, which publishes the result over REST, so no browser picks its numbers.
One subscription to tabletop:{id} receives the room, its chat and every game: subscriptions cover sub-topics (Topics).