---

UC Index

---

Global Shell

UC_4.1.1 — Dashboard Layout

1. Overview

References/Wireframe/Stage 2/Dashboard/Dashboard.png Overall dashboard layout — persistent header (top), persistent sidebar (left), main content area (right/center).

2. Screen Description

---

UC_4.1.2 — Sidebar Navigation

1. Overview

References/Wireframe/Stage 2/Dashboard/Dashboard - navigation expanded.png Sidebar shown in its expanded state.

2. Screen Description

---

UC_4.1.3 — Market Status Widget

1. Overview

🎬 Motion reference: Close In — Motion folder.

2. Trigger

• The Dashboard layout (Ref: UC_4.1.1) has rendered → frontend calls GET /system/market-status.
• A MARKET_STATUS_UPDATE WebSocket event arrives mid-session (Ref: BR_4.1.3.2).

3. Pre-conditions

• User is on the Dashboard (Ref: UC_4.1.1 §1 Overview).
• The Dynamic Timekeeper has populated the CME_Instrument_Details table with Official_Close_UTC, Halt_Start_UTC, Session_Open_UTC per asset class, via a daily cron task that pulls the official schedule directly from the CME Reference Data API (Ref: BR_4.1.3.5).

4. Post-conditions

• The widget displays the current state and, where applicable, a live countdown for each asset class the user trades.

5. Basic Flow — Futures Gateway

Applies when the user's selected asset class is Futures .

1. On Dashboard load, frontend calls GET /system/market-status.
2. Backend queries the CME_Instrument_Details table (populated daily from the CME Reference Data API — Ref: §3 Pre-conditions, BR_4.1.3.5), comparing server UTC time against Official_Close_UTC, Halt_Start_UTC, Session_Open_UTC to compute the current operational phase per asset class. These UTC values already reflect that day's DST shift and holiday-hours adjustment, sourced natively from CME — no separate DST logic runs in this step.
3. Backend responds with Array<{asset_class, state, short_text, next_state_timestamp}>.
4. Frontend renders the widget from this array. For any entry whose short_text follows the "Close in X minute(s)" pattern, frontend starts a client-side ticking timer computed as next_state_timestamp - current_client_time.
5. Live update: the Dynamic Timekeeper middleware calculates milestones independently per asset class/symbol and fires a webhook as each configuration approaches its threshold (Alert_Level: Warning_60/Warning_30/Warning_10/Lockout_Active/Enforcement_Complete/Halt_Active/Halt_Cleared/Session_Open).
6. Flow 24 Action 4 pushes a MARKET_STATUS_UPDATE WebSocket event to the Dashboard with payload {Widget_State, Widget_Short_Text}.
7. Frontend receives the event, looks up the matching entry in its asset-class-state array by Asset_Class, and updates only that entry: state ← Widget_State, short_text ← Widget_Short_Text.
8. In parallel, Flow 24 Action 3 pushes a NOTIFICATION WebSocket event (Notification_Severity, Message_Text) to populate the Notification Center.

6. Alternative Flow — Forex Gateway

Applies when the user's selected asset class is Forex. The Forex case reuses the same widget, endpoint, and event pipeline as the §5 Basic Flow; the only differences are the fixed close/rollover marker and that the warning schedule is auto-calculated against that fixed marker.

The rollover marker is a fixed 5:00 PM Eastern/New York time (17:00 ET) wall-clock instant, not a fixed UTC instant — the backend resolves it using a timezone-aware library targeting the America/New_York zone at local 17:00 every day, which natively yields 21:00 UTC in EDT or 22:00 UTC in EST without any hardcoded manual offset (Ref: BR_4.1.3.5). Equivalent Central Time expression: 16:00 CT.

No separate widget or field is needed for the Forex case — the dashboard timer displays the Forex fixed-rollover countdown the same way it displays the Futures overnight-margin countdown.

7. Exceptional Flow

N/A

8. Business Rules

BR_4.1.3.1: Client-Side Ticking Timer for Countdown States

For any asset-class entry whose short_text follows the "Close in X minute(s)" pattern, the frontend computes and locally ticks down next_state_timestamp - current_client_time, rather than polling the backend every second. The timer is purely a display computation; the authoritative state transition is still driven server-side by the Dynamic Timekeeper and delivered via the MARKET_STATUS_UPDATE event (Ref: BR_4.1.3.2).

BR_4.1.3.2: Alert Level → Widget State/Text/Severity Matrix

Flow 24's payload Alert_Level maps deterministically to Widget_State, Widget_Short_Text (max 15 characters), and Notification_Severity, per the table below (Ref: zapier_v7_full.txt "Flow 24" Notification Matrix):

[Asset_Class] and [Symbol] placeholders in the Discord/Slack/Dashboard copy text are replaced server-side before delivery — this widget only consumes Widget_State/Widget_Short_Text, not the full copy text (that belongs to the Notification Center, Ref: §5 step 8).

BR_4.1.3.3: Tie-Breaking Rule for Simultaneous Webhooks

If two MARKET_STATUS_UPDATE webhooks arrive at effectively the same time, they will always be for different asset classes (the Timekeeper fires independently per asset class/symbol — Ref: §5 step 5). When more than one asset class's entry must be prioritized for display (e.g. a single-asset-class widget slot, or ordering multiple entries), prioritize by proximity to lockout: show the asset class with the closest next_state_timestamp, or the most critical state if severity differs (e.g. Lockout takes priority over Open).

BR_4.1.3.4: Motion State Maps to Notification_Severity

🎬 Motion reference: Close In — Motion folder.

The widget's motion/visual state maps directly to the Notification_Severity flag pushed alongside Widget_State/Widget_Short_Text:

• INFO: standard default visual state — no special motion.
• WARN: triggers the initial color-change warning state.
• CRITICAL: triggers the high-alert blinking warning state shown in the motion file.

BR_4.1.3.5: DST (Daylight Saving Time) Handling — Source-Native for Futures, Timezone-Library-Native for Forex

• Futures — DST is handled upstream, at the data source, not by application logic. A daily cron task in the Node.js middleware (the Dynamic Timekeeper) pulls that day's official session boundaries directly from the CME Reference Data API and writes them into CME_Instrument_Details as Session_Open_UTC / Official_Close_UTC / Halt_Start_UTC (Ref: §3 Pre-conditions, §5 step 2). Because the CME Reference Data API itself already accounts for DST shifts and holiday hours when it publishes these schedules, the values landing in CME_Instrument_Details are correct UTC instants for that specific day with no additional DST calculation required anywhere downstream — the enforcement engine (§5 step 2) and the widget only ever read pre-resolved UTC timestamps.
• Forex — DST is handled natively by the runtime's timezone database, not by manual UTC-offset math. The institutional rollover is defined as a local wall-clock instant — 17:00 in the America/New_York IANA timezone (equivalent to 16:00 Central Time) — not a fixed UTC offset. The backend resolves this using a standard Node.js timezone-aware library (e.g. Intl/date-fns-tz/luxon, whichever the team standardizes on) configured to the America/New_York zone and targeting 17:00 local time every day. Because that IANA zone already encodes the EST (UTC-5) ⇄ EDT (UTC-4) transition dates, the library-computed UTC instant is 21:00 UTC while EDT is in effect and 22:00 UTC while EST is in effect automatically — the backend does not hardcode either offset or maintain its own DST transition-date table for Forex.
• No independent client-side DST logic in either flow. The frontend countdown (Ref: BR_4.1.3.1, next_state_timestamp - current_client_time) only ever diffs against the UTC timestamp already supplied by the backend — it performs no timezone or DST computation of its own, for either Futures or Forex.

9. Screen Description

---

UC_4.1.4 — Newsquawk Audio Stream

1. Overview

2. Trigger

The Dashboard layout (Ref: UC_4.1.1) has rendered.

3. Pre-conditions

• User is on the Dashboard (Ref: UC_4.1.1 §1 Overview).
• A valid long-lived audio access token, issued by Newsquawk, is available for the embedded widget to authenticate with (Ref: BR_4.1.4.2).

4. Post-conditions

• The embedded Newsquawk widget is playing (On) or stopped (Off), per user control — Off by default immediately after login (Ref: BR_4.1.4.3).

5. Basic Flow

1. Audio player widget renders in the persistent header, defaulting to Off on login (Ref: BR_4.1.4.3). No auto-play occurs.
2. On the user's first click of [On], the frontend mounts the embedded Newsquawk widget, which authenticates and streams audio directly from Newsquawk using the long-lived token (Ref: BR_4.1.4.1, BR_4.1.4.2). There is no separate relay/streaming server and no per-session token issuance step — the widget owns the entire connection.
3. User clicks [Off] to stop playback; state persists in the header until the user clicks [On] again or navigates away.

6. Exceptional Flow

• Widget connection drops mid-playback: reconnection behavior is owned entirely by the embedded Newsquawk widget itself (out of this platform's control) — the dashboard does not implement its own reconnect/retry logic on top of it.

7. Business Rules

BR_4.1.4.1: Token-Based Widget Authentication (Mandatory)

The embedded Newsquawk widget MUST authenticate using the token described in BR_4.1.4.2 to prevent unauthorized listening. This is a mandatory security requirement, not optional. There is no separate relay/streaming server in this design — the widget streams directly from Newsquawk, and the token is the only access-control mechanism (Source: BA confirmation, 2026-09-03 — supersedes the earlier Squawk Relay/Icecast 2 architecture).

BR_4.1.4.2: Long-Lived Audio Access Token (Supplied by Newsquawk)

The audio access token for BR_4.1.4.1 is a long-lived token issued directly by Newsquawk — not a short-lived JWT derived from the user's own session token, and not re-issued on the platform's session-refresh cadence. This supersedes the prior short-lived, session-derived audio-token design; the platform obtains this long-lived token from Newsquawk and supplies it to the embedded widget, with no periodic re-issuance tied to the 15-minute session-token refresh (Source: BA confirmation, 2026-09-03).

BR_4.1.4.3: Default Off at Login

The audio player defaults to Off immediately when the user logs in — the widget does not auto-play. Only 2 actions exist on this widget: On and Off; there is no separate "stopped" state beyond Off (Source: BA confirmation, 2026-09-03).

BR_4.1.4.4: Auto-Mute on Community Screen During a Live Broadcast

When the user navigates into the Community screen (Ref: Community tab → UC_4.5.1 Live Broadcast, UC_4.5.2 The Pit; SIM also UC_4.9.1 Discord Chat Stream one-way; LIVE also UC_4.14.1 Discord Chat Stream two-way) while the live broadcast is on (is_live == true, Ref: UC_4.5.1 §BR_4.5.1.10), the Newsquawk audio automatically mutes to avoid overlapping the community's own live audio — the On/Off toggle itself stays in its current state (does not flip to Off); only the audio output is silenced (Source: BA confirmation, 2026-09-03 — supersedes the prior "switches to Off" behavior).

• If the broadcast is not live when the user enters Community, no auto-mute occurs.
• If the broadcast goes live while the user is already on the Community screen, the audio mutes at that moment.
• On leaving the Community screen, or when the broadcast stops being live, the audio automatically unmutes (resumes at the volume/On-Off state it had before the mute) — the user does not need to manually re-enable it.
• Beyond the login default (BR_4.1.4.3) and this auto-mute behavior, there is no other automatic On/Off/mute rule for this widget — all other On/Off transitions are user-initiated (Source: BA confirmation, 2026-09-03).

8. Screen Description

---

UC_4.1.5 — Launch Trading Terminal

1. Overview

2. Trigger

The Dashboard layout (Ref: UC_4.1.1) has rendered, with the persistent sidebar (Ref: UC_4.1.2) visible.

3. Pre-conditions

• User is on the Dashboard with the persistent sidebar rendered (Ref: UC_4.1.2 §1 Overview).
• User's platform_selection value is available from the account state payload.

4. Post-conditions

• A new browser tab opens at tv.stacktrading.com, authenticated with the credentials supplied in the API payload.

5. Basic Flow

1. On Dashboard load, frontend checks platform_selection.
2. If platform_selection == "TradingView", the [Launch TV Web Terminal] action renders in the persistent sidebar (Ref: UC_4.1.2 §2 Screen Description). Otherwise, it is not rendered (Ref: BR_4.1.5.1).
3. User clicks [Launch TV Web Terminal].
4. Frontend opens a new tab (target="_blank") to tv.stacktrading.com, using the credentials supplied in the API payload.

6. Business Rules

BR_4.1.5.1: Button Visibility Gated by Platform Selection

The [Launch TV Web Terminal] action renders only when platform_selection == "TradingView". For every other registered platform — TradeSea (Futures/Rithmic, supersedes NinjaTrader 8 per CR-20260720-001), Quantower, ATAS, MotiveWave, Sierra Chart (all Futures/Rithmic), and MetaTrader 5 (Forex/MT5) — the action is not rendered at all; those are desktop applications the trader opens independently, outside the web dashboard. Confirmed per QnA_init_docs.md A-03. Per direct BA instruction (2026-08-07), this action lives in the persistent sidebar (Ref: UC_4.1.2), not the header — this reframes but does not change the visibility condition itself, which is unchanged from the original A-03 answer.

7. Screen Description

---

Changelog