UC_4.5.2: The Pit (Discord Server Widget)

---

Document References

---

1. Overview

References/Wireframe/Stage 2/Community & Live Broadcast/Community (with data).webp The Pit card in its linked state, with both metrics populated.

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 frontend calls GET /community/server-status.
• The 30-second polling interval elapses while the trader remains on the page → the frontend calls GET /community/server-status again (Ref: BR_4.5.2.3).

3. Pre-conditions

• The user is authenticated and is on the Community page. No further condition applies — account type (SIM / LIVE), trader level, and account status are irrelevant (Ref: BR_4.5.2.1).
• The "Server Widget" setting is enabled on the Stack Trading Discord server, so that the guild widget payload is publicly readable by the backend (Ref: BR_4.5.2.3).

4. Post-conditions

• The card renders in exactly one of two account states — Linked (Ref: §5) or Not linked (Ref: §6) — determined solely by whether discord_user_id is populated on the user record (Ref: BR_4.5.2.7).
• The two server-activity metrics are either both displayed with their current values, or both hidden (Ref: BR_4.5.2.5). They are never partially displayed and never show a stale value.

5. Basic Flow — Discord Account Linked

Applies when discord_user_id is populated on the user record.

1. The Community page renders. The card displays its section title and the [Enter PIT] action.
2. The frontend calls GET /community/server-status.
3. The backend serves the response from its Redis cache. On a cache miss, the backend first calls the Discord guild widget API, parses the payload, and stores it in Redis with a 30-second TTL (Ref: BR_4.5.2.3).
4. The frontend renders the Community Chat / Discord Gateway block together with the two metrics — Traders online and Traders in voice — from the response (Ref: BR_4.5.2.4). The block is display-only; it carries no CTA of its own (Ref: BR_4.5.2.2).
5. Every 30 seconds the frontend repeats step 2 as a silent background fetch and updates the two values in place. No loading state is rendered on these subsequent fetches (Ref: BR_4.5.2.3).
6. The trader clicks [Enter PIT] — the only CTA on the card in this state. The action resolves to the Discord server invite URL and attempts to launch the Discord desktop application, falling back to the Discord web client (Ref: BR_4.5.2.2).
7. Discord opens on the server's default landing channel. What the trader can do from there is determined by the Discord roles already held on their account, not by this card (Ref: BR_4.5.2.8).

6. Alternative Flow — Discord Account Not Linked

Applies when discord_user_id is null. This is the default state for a trader who has just purchased an Associate Track and has not yet acted on the onboarding email.

1. Steps 1–3 of §5 are unchanged. The section title, the [Enter PIT] action, and both metrics render exactly as in the linked state — the metrics do not depend on the trader's own link status (Ref: BR_4.5.2.4).
2. In place of the Community Chat / Discord Gateway block, the card renders the link-token instruction block headed Link your Discord account first (Ref: BR_4.5.2.7), containing three numbered steps and one supporting line:
   • Step 1 — Copy your token followed by the trader's link token, displayed truncated, with a [Copy] action (copy glyph + Copy label) that copies the full token value to the clipboard and confirms inline (Ref: BR_4.5.2.12).
   • Step 2 — Join the server followed by an [Open Discord] action (Discord icon + link label). This is the only place on the card where Open Discord appears (Ref: BR_4.5.2.2).
   • Step 3 — Type the command /link followed by your token in the #verify channel.
   • Supporting line — Complete verification to participate, access exclusive trading rooms, and unlock your badges.
3. The trader clicks [Copy] → the full token value is copied to the clipboard and the control's label changes to Copied + check glyph for 3 seconds, then reverts to Copy on its own (Ref: BR_4.5.2.12). No toast is raised. The token block stays visible; no state on the user record changes.
4. The trader clicks [Open Discord] (or [Enter PIT]) → Discord opens on the server's default landing channel. Because the trader has not yet submitted the token, they hold only the everyone role at this point, which grants read-only access to public channels (Ref: BR_4.5.2.8).
5. The trader navigates to #verify inside Discord and submits /link [token]. The Discord bot matches the token, writes discord_user_id to the user record, assigns the Associate Trader role, and deletes the token from the database (Ref: BR_4.5.2.6).
6. On the trader's next load of the Community page, the card renders the linked state (Ref: §5). The link-token instruction block is not rendered again for this account.

7. Exceptional Flow

• [If GET /community/server-status fails, times out, or returns no metric values] — both metric rows are hidden entirely. The last known values are not retained, and no — placeholder is rendered. The card shortens to its title, the gateway or token block, and the [Enter PIT] action (Ref: BR_4.5.2.5).
• [If a metric returns the value 0] — the value 0 is displayed. Hiding applies only to a failed fetch, never to a successfully fetched zero (Ref: BR_4.5.2.5).
• [If the trader's Discord roles have been revoked by Flow 7 (Digital Eviction)] — the card renders unchanged and remains fully usable. The trader can still open the server, but holds only the everyone role there. This card does not detect, display, or act on Discord-side role state (Ref: BR_4.5.2.8).
• [If the browser blocks the clipboard write] — the Clipboard API is unavailable (non-secure context) or the browser denies the permission. The control's label stays at Copy — it never changes to Copied, so the trader is never told a copy succeeded when it did not. The system displays Ref: TE-SYS-01. The token value remains selectable on screen so the trader can copy it manually (Ref: BR_4.5.2.12).
• [If the trader purchases a further evaluation while discord_user_id is already populated] — no new token is generated and the link-token instruction block is not shown again. The backend re-assigns the Associate Trader role directly (Ref: BR_4.5.2.6).

8. Business Rules

BR_4.5.2.1: Universal Access — No Account-Type, Level, or Account-Status Gating

The Pit is the default community lounge for all authenticated users. The card renders identically for SIM and LIVE accounts.

• SIM (Evaluation) accounts have full read and write access in #the-pit. There is no read-only mode, no locked state, and no upsell placeholder for SIM traders on this card.
• Read/write access is open to every active trader from Level 1 through Level 24. Only public, unverified visitors to the Discord server are restricted to read-only.
• Trader level does not change access to #the-pit. Level affects channel visibility elsewhere on the server — higher roles unlock private team channels, priority support routing, and partner areas — but never the lounge itself.
• Account risk status does not affect this card. A SIM trader under Soft Breach (Ref: UC_4.10.1), under Hard Breach (Ref: UC_4.10.2), or who has failed the Associate Track still sees and uses the card normally. Breach enforcement restricts trading only, not community access.
• The Hard Breach frosted-glass lock is scoped to the Command tab alone. That overlay exists to force the trader into a Reset or Re-buy, so it covers the Command Center and nothing else. The Community page — this card and My POD alongside it — stays fully reachable: a breached trader can still read the lounge and watch the broadcast (Ref: UC_4.5.1). Applying the overlay to the Community page is a defect, not a stricter reading of the rule.

BR_4.5.2.2: Custom Card with a Single Deep-Link CTA — Not an Iframe Embed

The Pit is a custom dashboard component. It does not embed the native Discord Server Widget iframe, and it does not host chat or voice inside the dashboard.

• [Enter PIT], in the card header, is the only CTA on the card in the linked state. It resolves to the Discord server invite URL, attempts to launch the Discord desktop application, and falls back to the Discord web client when the application is unavailable.
• The Community Chat / Discord Gateway block is display-only and carries no CTA.
• [Open Discord] exists in exactly one place: step 2 of the unlinked-account instruction block (Ref: BR_4.5.2.7), where it is the numbered action of a three-step procedure and must stay in sequence so the trader copies the token before leaving. Its behaviour is identical to Enter PIT.
• No channel-level deep link exists. Every CTA lands the trader on the server's default landing channel, not directly in #the-pit.

BR_4.5.2.3: Server Activity Metrics — Backend Caching Proxy

Metric data is served exclusively through the backend endpoint GET /community/server-status. Client browsers must never call the Discord API directly.

• The backend calls the Discord guild widget API https://discord.com/api/guilds/{Server_ID}/widget.json, parses the payload, and caches the result in Redis with a 30-second TTL.

• {Server_ID} (the Discord Guild ID) and the server invite URL are held as backend environment variables, not as configuration rows. Neither value exists in Table C — Global Variables, and neither is added to it: changing them is a deployment concern, not an Ops task. This is the point of difference from the Live Broadcast widget, whose Active_Broadcast_URL and Broadcast_Is_Live are Ops-editable Table C fields (Ref: UC_4.5.1).

• The frontend polls GET /community/server-status every 30 seconds as a silent background fetch. On the first load only, a skeleton occupying the same space as the two metric rows is rendered; every subsequent poll updates the values in place with no spinner, no skeleton and no layout shift. Flashing a loading state twice a minute would interrupt the trader's reading of a card they are not interacting with.

• Effective data freshness is therefore at most 30 seconds, and Discord is called at most once per 30-second window regardless of how many traders have the page open. The proxy exists specifically to prevent Discord from rate-limiting frontend traffic.

• The "Server Widget" setting must be enabled on the Discord server. No custom bot and no privileged gateway intent is required for these metrics.

• The aggregation of both metric values happens in the backend, on the cached payload. The frontend renders the two numbers as received and performs no counting or summing of its own.

Endpoint contract.

• Because the endpoint is public, it is rate-limited by IP at the edge rather than by user identity, and it must not be extended with any user-scoped field later — doing so would silently turn a public endpoint into a data leak.
• Field naming: the DTO keys match the UI labels one-for-one — traders_online → Traders online, traders_in_voice → Traders in voice (Ref: BR_4.5.2.4). Both carry headcounts of people, so name and value agree and no interpretation note is needed.

BR_4.5.2.4: Metric Definitions and Scope

Both metrics describe the entire Stack Trading Discord server, not the #the-pit channel alone, and neither is filtered by Discord role.

• Both metrics are headcounts of people, never counts of rooms or channels. Traders in voice answers "how many people are talking right now". Client rationale: "Displaying the number of active rooms does not show community engagement. The dashboard needs to reflect the total number of users actively participating in voice at that moment."
• Worked example — 3 voice rooms holding 4, 2 and 1 members renders Traders in voice 7, not 3.
• Neither metric displays a denominator or total. Traders in voice never renders as 7 / 40.
• Both values are derived from the same single widget.json payload already being fetched (Ref: BR_4.5.2.3). No second Discord call, no additional endpoint, and no channels traversal is required.
• #the-pit itself is a text channel and has no voice component. Traders in voice is deliberately server-wide and is not a measure of activity inside #the-pit.
• The voice rooms whose occupants are counted are in practice the per-pod rooms. Each POD is provisioned as a Discord Category containing one dedicated text channel and one dedicated voice channel, both visible only to that pod's members — PODs are not voice-only groups (Ref: BR_4.5.2.11).
• Neither metric is role-filtered. A count restricted to the Stack Trader / Associate roles is out of scope — it cannot be derived from the guild widget payload.

Labels. The two static labels rendered on the card are Traders online and Traders in voice. Both read literally — Traders in voice 7 means seven people are connected to voice. Neither is a room count.

• Both labels are wider than the word "traders" implies: the underlying counts include staff, moderators, unverified public members and any bot reporting presence. The card treats every server member as a trader for display purposes.

BR_4.5.2.5: Metric Failure Handling — Hide, Never Stale

When metric data cannot be obtained, both metric rows are hidden entirely and the card shortens accordingly.

• The last known values must not be retained and re-displayed.
• A — placeholder, an error message, and a retry action must not be rendered.
• The two metrics are hidden and restored together. One metric is never shown while the other is hidden.
• Hiding is triggered by a failed fetch only. A successfully fetched value of 0 is displayed as 0 — for example Traders in voice 0 outside active trading hours. 0 is a true reading of a real-time metric and must render; suppressing it would make the card change height on every 30-second poll.
• The hide-on-error behaviour is specific to this card and is not a Common Rule. Each widget states its own failure behaviour.

BR_4.5.2.6: Discord Link Token — Single-Use UUID, Never Rotated

The link token displayed on this card is the trader's Discord link token, generated once by Flow 1 Step 6 during onboarding and delivered by onboarding email.

• The token is a single-use UUID. It does not rotate, does not refresh, and does not expire.
• It persists in the database until the trader submits /link [token] in #verify. On success the bot writes discord_user_id to the user record, assigns the Associate Trader role, and deletes the token.
• One token binds to exactly one Discord account. The first Discord account to submit the token in #verify consumes it and becomes the account written to discord_user_id. The token is spent at that moment, so a second Discord account submitting the same value is rejected by the bot and no second discord_user_id is ever written for that trader. A trader therefore cannot link two Discord accounts, and two traders cannot share one token.
• The binding is not reversible from the dashboard. There is no unlink, re-link or "link a different Discord account" control on this card, and none is built. Correcting a wrong binding is an Ops action on the user record, outside this UC.
• There is no regeneration scenario. If the trader loses the onboarding email, this card displays that same existing token — a new token is never issued.
• The linking action is performed by a Discord slash command, not by a dashboard REST call. The dashboard's only responsibility is to display the token, enable copying it, and instruct the trader where to submit it.
• Once discord_user_id is populated, the token block is permanently hidden for that account.
• If the trader later purchases a further evaluation while discord_user_id is already populated, token generation is skipped entirely and the backend re-assigns the Associate Trader role directly. The trader is never asked to verify a second time.

BR_4.5.2.7: Unlinked-Account CTA — Mandatory Token Guidance Before Leaving for Discord

When discord_user_id is null, the dashboard must guide the trader to copy their link token before letting them leave for Discord. Sending an unlinked trader to the server without their token leaves them on the default everyone role with read-only public access, unable to unlock the paid trader roles they have already bought.

• Placement: the instruction block sits persistently inside the body of The Pit card, replacing the Community Chat / Discord Gateway block, alongside the My POD widget on the Community page. It is never rendered as a page-level banner above the Bento Grid — the block is part of the card, not a notice about it.
• The block is headed Link your Discord account first and carries three numbered steps plus one supporting line. Each step is a short action label followed by its control, so the trader can see what to do without reading a paragraph:

• Supporting line, below step 3: Complete verification to participate, access exclusive trading rooms, and unlock your badges. The copy states what the trader gains by verifying. An unverified trader holds only everyone / read-only public access (Ref: BR_4.5.2.8).
• Step 3 spells out the command name (/link) and the target channel (#verify) in one sentence. It must not be shortened to /link [token] alone — the trader has to know the token is typed after the command, and that the command only works in #verify.
• The instruction to use the #verify channel is mandatory, not optional — the server invite lands the trader on the default landing channel, and they must navigate to #verify themselves.
• The same link token is also surfaced in Settings. This document owns the Community-page presentation; the Settings presentation has no owning UC in the current WBS and must reference this rule rather than restate it.

BR_4.5.2.8: Discord Permissions Are Server-Side — This Card Does Not Reflect Them

What a trader can do after entering the server is governed entirely by their Discord roles. This card neither reads nor displays that state.

• Any user who follows the invite link is initially assigned the everyone role, which grants read-only access to public channels. Write access requires submitting the link token in #verify.
• Flow 7 (Digital Eviction) executes POST /discord/revoke-all-roles, which strips the trader's title and pod roles. It does not kick the trader from the server and does not delete discord_user_id. Such a trader still passes the linked-state check in §5 and still sees the standard card, but has dropped to read-only public access on the Discord side.
• Flow 38 (Digital Concierge) monitors #the-pit and #verify for operational complaint keywords, and on detection deletes the message, posts an automated public reply, and opens a Freshdesk ticket (Ref: CR-20260720-004). This behaviour occurs entirely inside Discord and produces no dashboard-side UI.
• The dashboard knows only whether the account is linked — the binary state of discord_user_id being populated or null. It does not know whether the trader is currently a member of the server, currently online, or currently holds any given role, and it performs no real-time permission check against Discord.
• [Enter PIT] never changes state. It is not relabelled to Rejoin, never carries a Joined badge, and is never disabled once the trader has joined. There is no data to drive such a state: a trader who joined and then left the server is indistinguishable, from the Dashboard's side, from one who is still in it. The control stays a permanently active link into the server in every card state.
• A Flow 7 revocation is invisible on this card by design. A trader whose Associate Trader role was stripped after failing still sees the ordinary card, still clicks through, and lands in the server on read-only public access. The Dashboard shows no badge, banner or warning about the demotion, because it reads the link flag and not the role set. Surfacing it would require a new Discord permission read that is not in scope.

BR_4.5.2.9: No Dashboard Surface for Discord Announcements

Discord announcements — level promotions, referral wins, and similar broadcasts — exist only inside Discord. No dashboard bell notification, toast, badge, or unread indicator is built for them, and this card does not surface them in any form.

Level-up announcements are no longer routed to #the-pit; that routing change is owned by CR-20260827-001 and changes nothing on this card.

BR_4.5.2.10: Independence from Live Broadcast State

The Pit has no operating hours and no online/offline state. It renders identically whether a broadcast session is live or not, and its 30-second metric polling is unaffected by broadcast state (Ref: UC_4.5.1).

#the-pit and #live-broadcast-chat are two distinct text channels on the same server. #the-pit is the general community lounge and is the destination of this card. #live-broadcast-chat is dedicated to the livestream and feeds the separate chat panel (SIM one-way: Ref: UC_4.9.1; LIVE two-way: Ref: UC_4.14.1, not yet documented in this repo). The two are never merged and never share a message feed.

BR_4.5.2.11: POD Discord Structure — Context for the Voice Metric

This rule records the Discord-side structure whose occupants the Traders in voice metric counts. It is a server-provisioning requirement, not dashboard behaviour, and this card neither creates nor reads it.

• A POD is not a bare voice channel. Each POD is provisioned as a Discord Category containing exactly one dedicated text channel and one dedicated voice channel.
• Both channels are permissioned so that only the members of that specific POD can see and enter them.
• The members connected to those per-pod voice channels are the ones the Traders in voice headcount picks up — each carries a channel_id in the widget payload while connected (Ref: BR_4.5.2.4).
• Provisioning itself belongs to the Pod Mentorship module (POST /create-pod-channel, UC_4.14.2 — not yet documented in this repo) and to Discord Server Details.md. This UC restates the structure only so the metric formula is unambiguous.

BR_4.5.2.12: Copy Control Behaviour — Inline Copied Confirmation, No Toast

The [Copy] control beside the link token follows the platform's copy-to-clipboard pattern, owned by BR_4.6.1.4 (Settings → Connections & Credentials). It is restated here because this card renders the control in its own unlinked state; the behaviour is identical and must not diverge.

• Copying is a pure client-side action: it calls no API, writes nothing to the database, and changes no account state. It does not consume the token, does not populate discord_user_id, and does not alter card state (Ref: BR_4.5.2.6).
• On click, the control writes the full, untruncated UUID to the clipboard — never the visually truncated display value (Ref: BR_4.5.2.6).
• The control's label changes from Copy + copy glyph to Copied + check glyph for 3 seconds, then reverts to Copy on its own. No further click is needed to reset it.
• Clicking the control again while it is in the Copied state re-copies the value and restarts the 3-second timer.
• No toast is raised on success. The inline label change is the only confirmation, so repeated copying does not stack notifications.
• This card holds exactly one copy control, so the "only one control in the Copied state at a time" clause of BR_4.6.1.4 has no effect here — it is stated only to confirm the two screens share one pattern.
• Failure handling: Ref: §7 Exceptional Flow.

9. Screen Description

Related behaviour owned elsewhere: when the trader navigates into this screen, the Newsquawk audio stream in the persistent header switches to Off automatically. That rule is owned by BR_4.1.4.4 and is not restated here.

---

Changelog