UC_4.14.1: Discord Chat Stream (TWO-WAY)

---

Document References

---

1. Overview

Design states covered by this UC (client design pack, 2026-08-26):

2. Trigger

• The trader navigates to the Community page via the Community tab in the persistent sidebar (Ref: UC_4.1.2 §2 Screen Description) → the chat component mounts and issues its one-time hydration request.
• A new message is posted in the Discord #live-broadcast-chat channel, by any source, → the DISCORD_CHAT_STREAM WebSocket pushes it to the Dashboard (Ref: BR_4.14.1.7).
• The trader submits a message from the panel — by pressing Enter or clicking [Send] (Ref: BR_4.14.1.6).

3. Pre-conditions

• The user is authenticated and is on the Community page.
• GET /community/live-broadcast has returned the current is_live value. This endpoint and its contract are owned by UC_4.5.1 and are not redefined here (Ref: BR_4.14.1.8).
• To read the feed: nothing further. The feed is visible to every authenticated user, SIM and LIVE alike (Ref: BR_4.9.1.1).
• To post: the account is LIVE at Level 1 or above and discord_user_id is populated on the user record. Both conditions must hold — see the matrix in BR_4.14.1.1.

4. Post-conditions

• The panel renders in exactly one of the six states listed in §1.
• A message accepted by the backend has been enqueued in Redis. It is not guaranteed to appear on any Dashboard — it appears only if the dispatcher posts it successfully, over the webhook route or over the bot fallback route, and it survives both moderation layers (Ref: BR_4.14.1.4, BR_4.14.1.10).
• No message is ever transmitted to Discord from an account that fails either gate in BR_4.14.1.1.

5. Basic Flow — Broadcast Live, Discord linked (LIVE Level 1+)

1. The Community page renders. is_live == true is returned by GET /community/live-broadcast (Ref: UC_4.5.1 §5), so the chat panel opens together with the video player (Ref: BR_4.14.1.8).
2. On component mount, the frontend executes a single hydration request and renders the 50 most recent messages held in the backend Redis cache, then opens the DISCORD_CHAT_STREAM WebSocket subscription. Feed rendering, ordering, the rolling window, author naming, the Host highlight, auto-scroll and Read more behave exactly as on the SIM panel (Ref: BR_4.14.1.7).
3. The account passes both gates in BR_4.14.1.1, so the input row renders enabled, with the placeholder Type a message and an active [Send] control (Ref: BR_4.14.1.2).
4. The trader types a message. Composition is constrained to plain text and Unicode emoji, hard-capped at 1,916 characters by the input's maxlength, with no character counter and no emoji picker, GIF picker, attachment control or @mention auto-complete (Ref: BR_4.14.1.6).
5. The trader presses Enter, or clicks [Send]. Shift+Enter inserts a line break instead of submitting (Ref: BR_4.14.1.6).
6. The frontend calls POST /community/chat/send with { user_id, message_text }. The backend validates the session, checks the per-user rate limit, pushes the message onto the Redis broadcast queue, and returns HTTP 202 Accepted immediately (Ref: BR_4.14.1.3, BR_4.14.1.5).
7. On the 202 the frontend clears the input and re-enables it for the next message. It does not render the message in the feed, does not show a pending bubble, and does not show a delivery spinner (Ref: BR_4.14.1.4).
8. The dispatcher drains the queue. While the queue holds 5 or fewer pending messages and the webhook budget is available, it sends one webhook request per message, overriding username and avatar_url from the sender's Dashboard profile — so the message lands in #live-broadcast-chat under the trader's own name and photo, not as a bot transcript line (Ref: BR_4.14.1.3, BR_4.14.1.12).
9. The message passes both server-side moderation layers — Discord native AutoMod, then the Flow 38 monitor (Ref: BR_4.14.1.10).
10. The posted message is pushed over DISCORD_CHAT_STREAM. It now appears in the panel of every connected trader, including the sender's own, as an ordinary bubble (Ref: BR_4.14.1.4, BR_4.14.1.7). Which name and Host styling that bubble carries for a webhook-posted message is not yet settled — see §10 item 15.

6. Alternative Flows

6.1 — Live, Discord account not linked

Applies when is_live == true and discord_user_id is null. This is the most common state for a trader who has just been provisioned onto a live account and has not yet opened their onboarding email.

1. The message feed renders in full and behaves exactly as in §5 steps 1–2 — reading is never gated (Ref: BR_4.9.1.1).
2. The input row renders locked: a 🔒 icon inside the field, the placeholder Link your Discord account first to unlock chat, and a disabled [Send] control. The field cannot receive focus (Ref: BR_4.14.1.2).
3. In the same page view, The PIT card replaces its Community Chat / Discord Gateway block with the three-step link-token instruction block headed Link your Discord account first. That block is owned by BR_4.5.2.7 and is not duplicated by this UC — the chat panel renders no instructions, no CTA and no token of its own.
4. The trader completes /link [token] in #verify inside Discord. The bot writes discord_user_id to the user record and assigns the trader's Discord role (Ref: BR_4.5.2.6).
5. The input row unlocks on the next page load or Community-page mount. The panel does not subscribe to a linking event and does not poll discord_user_id, so the unlock is not live within the current view (Ref: BR_4.14.1.1).

6.2 — Broadcast Offline

Applies whenever is_live == false, for every account regardless of level or linking state.

1. The chat panel clears the active messages and transitions to the empty state.
2. The panel body displays No live chat with the supporting line Chat will open when the session goes live.
3. The input row stays present but locked, and its placeholder changes to Waiting for session.... [Send] is disabled. This placeholder wins over the unlinked placeholder of §6.1 (Ref: BR_4.14.1.2).
4. When the broadcast returns to is_live == true, the panel re-opens and the flow restarts at §5 step 2 — the feed is re-hydrated from Redis; cleared messages are not restored from the client (Ref: BR_4.14.1.8).

7. Exceptional Flow

• [If the trader submits faster than the per-user rate limit] — the backend rejects the request and the panel displays the inline notice Message rate limit reached. Please wait a moment. The composed text is retained in the input so the trader can resubmit without retyping (Ref: BR_4.14.1.5).
• [If the queue backs up past 5 pending messages, or the webhook's 30-requests-per-60-seconds budget is exhausted] — delivery switches to the bot batching route for as long as the condition holds. Messages sent in that window arrive in Discord as a single concatenated post under the bot's identity, not under the trader's name and photo. Nothing on the Dashboard signals the switch — no notice, no badge, no change to the input row — and the feed will therefore show both bubble styles inside one session (Ref: BR_4.14.1.3, BR_4.14.1.12). See §10 item 16.
• [If the trader has no Dashboard photo] — the webhook payload falls back to the linked Discord account's avatar, and if that does not exist either, to the webhook's own configured avatar. The Dashboard panel itself is unaffected: it renders no avatar in any case (Ref: BR_4.14.1.12).
• [If Discord cannot fetch the avatar_url supplied in the payload] — for example a private or expired S3 URL — Discord renders the webhook's own avatar and the message is still delivered. The trader is not told, and no retry is performed. See §10 item 13.
• [If the message is blocked by Discord AutoMod] — it never reaches the channel, so DISCORD_CHAT_STREAM never fires for it. The message simply never appears, on the sender's Dashboard or anyone else's. No error, no toast, no flagged bubble and no removal animation is built. This silence is the confirmed design, not a defect (Ref: BR_4.14.1.10) — see §10 item 4 for the open question on sender feedback.
• [If the message is intercepted by Flow 38 as an operational complaint] — the Discord bot deletes it inside Discord and opens a Freshdesk ticket at Priority = High. The Dashboard renders nothing for it (Ref: BR_4.14.1.10). ⚠️ For a message that arrived over the webhook route, the ticket step has no discord_user_id to resolve the trader's email from — see §10 item 14.
• [If the WebSocket connection drops mid-session] — the panel shows the Reconnecting… chip beside the Live chat header, retains the bubbles already rendered, and reconnects automatically with exponential backoff. On reconnect it re-hydrates the 50 most recent messages from Redis. The input row's own state is unaffected — a linked LIVE trader can still compose and submit, because the outbound path is HTTP and does not depend on the WebSocket (Ref: BR_4.14.1.9).
• [If POST /community/chat/send fails with a network or 5xx error] — the composed text is retained and the input stays enabled. No message was queued, so nothing will arrive over the WebSocket.
• [If the broadcast goes offline while the trader's message is still in the Redis queue] — the message may still be posted to Discord by the worker, but the panel has already cleared and locked, so the sender never sees it land. No cancellation of queued messages is performed (Ref: BR_4.14.1.8).
• [If the trader's Discord roles are revoked by Flow 7 Digital Eviction] — posting stops working from the Discord side. The Dashboard reflects this only after the account's level/status is re-read on the next page load (Ref: BR_4.14.1.11).
• [If a message contains a custom Discord server emoji, an @ mention, or a link] — it renders as raw text. Standard Unicode emojis render natively (Ref: BR_4.14.1.6, BR_4.9.1.7).

8. Business Rules

BR_4.14.1.1: Posting Requires Two Independent Gates — Level and Discord Link

Reading the feed is universal (Ref: BR_4.9.1.1). Posting requires both of the following, and neither substitutes for the other:

Resulting input-row state:

• The gates are evaluated on page load / component mount only. The panel does not poll discord_user_id and does not subscribe to a linking event, so a trader who links mid-session must reload to unlock the input.
• The link-token instruction block that tells the trader how to link lives on The PIT card and is owned by BR_4.5.2.7. The chat panel states the blocker; it does not restate the remedy.

BR_4.14.1.2: Input Row State Machine — Precedence Order

The input row is never removed from the layout. Locking it keeps the panel height and the page grid stable, which is the constraint the client stated twice for this page ("so the UI grid does not break", "Hiding the component will break your frontend CSS grid layout").

Several lock conditions can hold at once. They are resolved in this fixed order — the first match wins, and lower rows are not evaluated:

Why session state outranks eligibility. When the broadcast is offline nobody can post, so the session reason is both the nearer cause and the one that will clear first. Showing an eligibility message while the chat is closed for everyone would tell the trader to fix something that is not currently blocking them.

Why the Level copy outranks the linking copy. Linking Discord does not raise a Level 0 account, so Link your Discord account first to unlock chat would be actively misleading advice for a SIM trader.

✅ Locked, not hidden — confirmed by BA on 2026-08-26, following the finalized design. Client answer A18 had said that for an unlinked user "the ability to send messages should be hidden" (hidden outright, not merely disabled). The design pack of 2026-08-26 instead draws the row present and locked, with a 🔒 icon and an explanatory placeholder, and that is the behaviour this UC specifies. Two reasons carried the decision: a disappearing input explains nothing to a trader who does not know why they cannot type, and removing the row contradicts the client's own grid-stability constraint ("so the UI grid does not break", "Hiding the component will break your frontend CSS grid layout"). A18 is superseded on this point and must not be re-opened from the QnA file — see the closed-item table in §10.

BR_4.14.1.3: Outbound Delivery — Two Routes, Webhook First, Bot Batching as the Pressure Valve

The Dashboard never talks to Discord directly. Every outbound message is queued in Redis and answered with HTTP 202 before any Discord call is attempted (Source: RFQ_ Stack Trading Prop Tech V7.pdf §2.3). What CR-20260903-001 changes is how the queue is drained: a Discord Webhook is now the default delivery route, and the Batch Worker concatenation of §2.3 survives only as a fallback for burst traffic.

The client's reason for the change, verbatim: "That UI is pretty ugly... I realize this batching method was originally outlined in the V7 spec to manage rate limits, but the visual result is.. yikes."

Pipeline

Route selection

Limits the dispatcher must respect. Both routes are paced by two separate token buckets, one per route, so that Discord never rejects a send:

• Why 1,916 and not 2,000. A single message is capped below the Discord ceiling so that it can never overflow the post it is wrapped in when route B concatenates it. The 84-character headroom absorbs the [Name]: prefix and the newline separator of the batched format. The cap therefore exists for route B but is enforced on every message, whichever route ends up carrying it.
• Endpoint path. POST /community/chat/send is the official path, confirmed by the client to supersede the POST /chat/send written in the WBS, so that it sits in the same group as GET /community/live-broadcast (Source: Stage 2 - Dashboard & Fomula (Community).csv — Discord Chat Stream / Endpoints A1, Adrian Stack).
• 202, not 200 — unchanged by this CR. The response carries no message ID, no delivery status, no echo of the payload and no indication of which route will carry the message. It confirms acceptance into the queue and nothing more (Ref: BR_4.14.1.4).
• The route is invisible to the frontend. No field, no header and no UI element tells the trader whether their message went out over the webhook or the bot. The frontend behaves identically in both cases.
• Batching is outbound-only. The inbound stream is never batched or delayed (Ref: BR_4.14.1.7).
• Route B is no longer the normal case. Under v1 aggregation began as soon as two traders posted inside the same second; it now begins only once the queue has actually backed up past five pending messages. At ordinary broadcast traffic the feed should show one webhook message per trader.

⚠️ Route B keeps the v1 problems, at reduced frequency. Whenever the fallback is active, several traders' text is still merged into one bot-authored post — so the attribution question of §10 item 2 and the collateral-moderation risk of item 6 remain live for exactly the burst window the client cares most about. The webhook route removes them; the fallback does not.

BR_4.14.1.4: No Optimistic Rendering — the Feed Is Read-Only in Both Directions

The Live Chat feed is a fully read-only component driven exclusively by DISCORD_CHAT_STREAM. The act of sending writes nothing to it (Source: Stage 2 - Dashboard & Fomula (Community).csv — Discord Chat Stream / Business logic A20, Adrian Stack, 2026-08-18).

• The sender's own message is not styled differently from anyone else's. There is no "me" bubble alignment, no sent/delivered tick and no local echo.
• Consequence for QA: a short delay between pressing Enter and the message appearing is expected behaviour, not a bug. The round trip covers a Redis hop, a worker cycle, a Discord API call and a WebSocket push.

BR_4.14.1.5: Per-User Rate Limit and Its Inline Notice

The endpoint enforces a standard per-user rate limit of 1 request per second per user, to stop a single trader flooding the Redis memory queue ahead of the batch worker (Source: Stage 2 - Dashboard & Fomula (Community).csv — Discord Chat Stream / Endpoints A2, Adrian Stack).

• This is the only custom gate at the endpoint. There is no custom content-moderation layer in the backend — content filtering is entirely Discord's (Ref: BR_4.14.1.10).
• On rejection the panel renders the inline notice Message rate limit reached. Please wait a moment. inside the chat panel, adjacent to the input row. It is an inline notice, not a modal and not a global toast.
• The composed text is retained in the input on rejection — the trader must not have to retype. The notice clears on the next successful submission or when the trader edits the input.
• The limit is enforced server-side. The frontend must not implement a competing client-side timer as the source of truth, though it may disable [Send] briefly to reduce obvious double-clicks.

BR_4.14.1.6: Composition Constraints — a Light Text Relay, Not a Discord Client

The client's framing for the whole panel: "we are building a lightweight text relay, not re-creating Discord."

• CR-02 does not apply to this field. CR-02 §2.2 sets a 255/500-character default with an out-click error, and CR-02 §2.3 prescribes an Enter [field's label] placeholder. Both are overridden here by the client's explicit answers: the cap is 1,916 with block-on-limit behaviour (no error message), and the placeholders are the four strings fixed in BR_4.14.1.2.
• Whitespace-only input is treated as empty and is not submitted; [Send] performs no request for it.

BR_4.14.1.7: Inbound Render Contract — Shared with UC_4.9.1, Not Restated Here

The inbound direction is identical for SIM and LIVE. It is owned by UC_4.9.1 and referenced here rather than duplicated, so that a change lands in one place.

LIVE-specific deltas on top of that contract:

• The badge label follows the count of unseen messages: New Message for exactly one, New Messages for two or more. Both labels appear in the design pack. See §10 item 3.
• The Read less control is rendered inline at the end of the expanded body, inside the bubble, in the 2026-08-26 design pack. BR_4.9.1.9 instead specifies a sticky control at the bottom right of the chat window. The two panels are the same component and must not diverge — see §10 item 3.
• The trader's own messages arrive through this same inbound path and receive no special treatment (Ref: BR_4.14.1.4).

BR_4.14.1.8: Chat Lifecycle Bound to the Broadcast is_live Flag

The chat panel opens and closes at the exact same moment as the video broadcast. Both are driven exclusively by the is_live flag from GET /community/live-broadcast; there is no separate schedule, field or flag that could open the chat earlier or hold it open later. The endpoint contract and its two-call cadence are owned by BR_4.5.1.3 and are not duplicated here.

• On the transition to offline the panel clears the active messages immediately and switches to the empty state of §6.2. Messages are not retained as a read-only archive; there is no post-session or intermediate state.
• On the transition back to live the panel re-hydrates from Redis. Cleared messages are never restored from client memory.
• Outbound-specific consequence. The lifecycle is a UI rule. Messages already accepted with a 202 stay in the Redis queue and are not cancelled when the session ends — the worker may still post them to #live-broadcast-chat after the panel has closed. The Dashboard offers no cancellation, no "unsent" state and no confirmation of what happened to an in-flight message. Discord is the system of record; the Dashboard is a window onto it that closes with the session.
• Only the chat component re-renders on a session transition. Pod and The PIT hold their state, per BR_4.5.1.8.

BR_4.14.1.9: WebSocket Reconnection — the Reconnecting… State

The panel applies the shared reconnection rule CR-14: exponential backoff, automatic reconnection, and last-known values retained rather than cleared.

• Indicator. While the socket is down or reconnecting, a Reconnecting… chip with a small spinner renders beside the Live chat panel header, per the 2026-08-26 design pack. It is not a full-width banner and not an overlay.
• The message list is not cleared and not dimmed. Bubbles already rendered stay exactly as they are. This is the point of the rule — a dropped socket must not look like an ended session, which has its own distinct empty state (Ref: BR_4.14.1.8).
• On successful reconnect the panel re-runs the single hydration request for the 50 most recent messages, so any message missed while disconnected is recovered, then resumes streaming. The chip disappears.
• The input row is unaffected. Outbound submission is plain HTTP and does not depend on the WebSocket, so an eligible trader can still send while the chip is showing. Their message will surface once the socket recovers.
• The trader is never asked to refresh the page manually.

BR_4.14.1.10: Moderation Is Two Server-Side Layers, and Both Are Silent to the Sender

There is no client-side profanity filter and no custom moderation layer in the backend. Filtering happens on the Discord side, in two independent layers, before a message can ever reach DISCORD_CHAT_STREAM.

• Flow 38 monitors #live-broadcast-chat. Its scope was extended from #the-pit + #verify to three channels by CR-20260818-002. The client's reasoning: AutoMod does not understand trading context, so without layer 2 a complaint about lag would be published globally on the dashboard with no ticket raised — and "a live broadcast is the worst possible time for a public support escalation." The rest of the Flow 38 pipeline is unchanged.
• Ticketing is Freshdesk, not Zendesk. The source documents say Zendesk; CR-20260720-004 supersedes them.
• The sender receives no feedback in either layer. No error state, no flagged bubble, no removal animation, no toast. From the Dashboard's point of view the message never existed. This is the confirmed design and must be recorded so QA does not raise it as a defect — but the client has not yet ruled on whether some feedback is wanted; see §10 item 4.
• Two unresolved consequences of relaying through a bot are recorded in §10 items 5 and 6: whether AutoMod evaluates bot-authored messages at all, and what happens to innocent messages bundled into an aggregated payload alongside a blocked one. Item 5 now applies to both delivery routes — neither a webhook post nor a bot post is authored by the trader's own Discord account (Ref: BR_4.14.1.3).
• ⚠️ Layer 2 loses its lookup key on the webhook route. Flow 38 opens its Freshdesk ticket by resolving the trader's email from the discord_user_id of the message author. A webhook-posted message has no Discord user as its author — only an overridden display name — so that key does not exist. Read literally, an operational complaint sent from the Dashboard would still be deleted but would raise no ticket, which is precisely the outcome CR-20260818-002 was raised to prevent. Blocking for BE — see §10 item 14.

BR_4.14.1.11: Posting Privilege Follows Discord Roles — Digital Eviction

Posting rights live on the Discord side, so they are removed on the Discord side. Flow 7 §Digital Eviction calls POST /discord/revoke-all-roles, and the bot strips Pod Member, Pod Leader and all Title Roles — including Associate Trader — from the trader's discord_user_id.

• The trader is not kicked from the server and discord_user_id is not deleted. They drop to the default everyone role, which grants read-only public access.
• Effect on this panel: gate G2 in BR_4.14.1.1 still passes — the account is still linked — but gate G1 no longer does, because the account is no longer a LIVE Level 1+ trader. On the next page load the input row renders locked with the Level copy of priority 2 in BR_4.14.1.2.
• The change is not live within the current view. The panel evaluates the gates on mount only. Until the trader reloads, the input can still appear enabled; a submission then reaches the queue, and the bot's post is refused by Discord because the author lacks Write scope on the channel. The message silently never arrives — the same silent outcome as a moderated message (Ref: BR_4.14.1.10).
• If discord_user_id is NULL the revoke endpoint drops the action and returns 200 OK; nothing on this panel changes, because such an account was already locked by gate G2.
• A SIM resignation revokes too, through a different caller. The revoke endpoint is reached from Flow 20, not Flow 7, and it strips the same roles; discord_user_id and the trader's server membership are kept, and the role is reassigned via /manage-discord-role on repurchase (Ref: BR_4.11.2.9). The effect on this panel is identical to the LIVE path above.

BR_4.14.1.12: Outbound Identity — the Webhook Posts as the Trader, Not as the Bot

A Discord webhook lets an external application override exactly two fields on every payload it sends: username and avatar_url. Route A populates both from the trader's Dashboard profile, so the message appears in #live-broadcast-chat as though the trader had typed it in the Discord app themselves (Source: CR-20260903-001, Adrian Stack — "The message will appear in the Discord channel looking exactly as if the trader posted it directly, displaying their actual name and profile picture.").

Webhook payload

Avatar priority — what renders in the Discord app, not on the Dashboard. Evaluated top-down; the first case that resolves wins and the rest are not consulted.

• This governs the Discord surface only. The Dashboard chat bubble renders no avatar at all, in this UC or in UC_4.9.1 — it is author name, time and body (Ref: §9 row 4). This rule changes what Discord renders, and adds nothing to the panel.
• Messages typed natively in the Discord app are untouched. They keep Discord's own author metadata — nickname, role suffix and role colour — exactly as before (Ref: BR_4.9.1.6). Only the Dashboard-originated direction is overridden.
• Priority 3 is not "no picture". A Discord message always carries an avatar. Omitting avatar_url does not fall through to the trader's Discord avatar — the webhook has no idea which user is behind the payload — it falls through to the image configured on the webhook itself in the Discord server settings. Priority 3 is therefore an ops-config item for Stack Trading (which image sits on the webhook), not a code branch. See §10 item 13.
• Priority 2 is an active Discord API read, not a default. For the same reason, reaching priority 2 requires the backend to look the trader's avatar up (GET /users/{discord_user_id} → avatar hash → CDN URL) and pass it in explicitly. This is new backend scope, and it reverses BR_4.6.2.13, closed on 2026-08-27 with the client's own rule: "StackTrading never pulls an avatar or a name from the Discord API, on any surface, as a primary value or as a fallback." CR-20260903-001 is the newer client instruction and therefore wins, but the reversal must be confirmed rather than assumed — see §10 item 12.
• Route B carries no identity. While the bot fallback is active the post reverts to the bot's name and avatar, with each line prefixed [Name]: (Ref: BR_4.14.1.3). Identity is a property of the route, not of the message.
• The trader still cannot choose what is shown. Both fields are derived server-side from the Users record. There is no chat-identity setting anywhere in the Dashboard, and no way to post under a name the trader has not already been assigned.

9. Screen Description

Related behaviour owned elsewhere:

• The link-token instruction block shown on The PIT card when discord_user_id is null is owned by BR_4.5.2.7. This panel states the blocker only.
• When the trader navigates into the Community screen, the Newsquawk audio stream in the persistent header switches to Off automatically. Owned by BR_4.1.4.4.

10. Open Items Pending Client Confirmation

Closed by this document:

---

Changelog