---

UC_4.8.1 — PnL Gauge

1. Overview

References/Wireframe/Stage 2/Dashboard/Dashboard.png PnL Gauge, "Starting point" state, populated. References/Wireframe/Stage 2/Dashboard/Dashboard - Day 0.png PnL Gauge, "Starting point" state, empty (Day 0, no trades yet). References/Wireframe/Stage 2/Dashboard/Level Up.png PnL Gauge, "Level Up" state. References/Wireframe/Stage 2/Dashboard/Drawdown defense (level 9+).png PnL Gauge, "Drawdown defense enabled" state (LIVE reference only — N/A on SIM, Ref: BR_4.8.1.1). References/Wireframe/Stage 2/Dashboard/Dashboard - Hard breach (T+0 - T+10).png PnL Gauge, "Breached (Account Disabled)" state, with the rest of the Overview screen desaturated (Frosted Glass).

🎬 Motion reference: PnL Gauge state-transition animations (Google Drive)

2. Trigger

• The Overview screen (Ref: UC_4.1.1) has rendered.
• An ACCOUNT_METRICS WebSocket event arrives while the user is on the Overview screen (Ref: BR_4.8.1.3).
• A LEVEL_STOP_BREACH or LEVEL_PROMOTION WebSocket event arrives (Ref: BR_4.8.1.1).

3. Pre-conditions

• User is on the Overview screen (Ref: UC_4.1.1 §1 Overview) with an active SIM account.

4. Post-conditions

• The dial displays the trader's current risk/reward position (Hard Stop Loss ↔ Profit Target, needle at current Net PnL) and continues to update live for the remainder of the session.

5. Basic Flow

1. On Overview screen load, frontend calls GET /current-level-detail, which returns the trader's Market_Loss_When_Stopped (Hard Stop Loss threshold) and Profit_Target (Ref: BR_4.8.1.2).
2. Frontend renders the dial scale: left end (minimum) = -Market_Loss_When_Stopped, right end (maximum) = +Profit_Target (Ref: BR_4.8.1.2), and the two per-state labels beside the dial (Ref: BR_4.8.1.4).
3. Frontend subscribes to the ACCOUNT_METRICS WebSocket channel; on each update, the needle position and the live dollar value below it are set to the current Net PnL (Unrealized + Realized, equivalently equity − allocated_capital) (Ref: BR_4.8.1.3).
4. [If a LEVEL_STOP_BREACH event arrives] the dial transitions to the "Breached (Account Disabled)" state (Ref: BR_4.8.1.1, BR_4.8.1.5).
5. [If a LEVEL_PROMOTION event arrives] the dial transitions to the "Level Up" state (Ref: BR_4.8.1.1, BR_4.8.1.4).

6. Exceptional Flow

• WebSocket/API connection drops: the dial retains its last-known values (stale data) while the client applies exponential backoff and automatically reconnects, per the shared WebSocket reconnection resiliency rule (CR-14).
• Shadow Mode (Passing Associate Track, awaiting Live provisioning): the gauge remains active and continues to display the live dial/needle, in a Read-Only mode (Source: RFQ_ Website and Dashboard Implementation V7.pdf, "PnL Gauge is active since it shows them the timer").

7. Business Rules

BR_4.8.1.1: Four Dial States — "Drawdown Defense Enabled" is N/A on SIM

The dial requires frontend state management for 4 distinct visual states: Starting point, Drawdown defense enabled, Breached (Account Disabled), and Level Up (Source: RFQ_ Website and Dashboard Implementation V7.pdf §Part C, "PnL Gauge"; visual reference: wireframes listed in Section 1).

The "Drawdown defense enabled" state is listed here for structural completeness with the source, but never triggers on SIM — the underlying Defense Protocol (48h cooling-off, Table F) applies only to Level 9+ traders on LIVE (Ref: UC_4.14.4, LIVE, not yet documented in this repo). SIM has only a single active tier (Level 0 — evaluation, binary pass/fail) with no Defense Protocol equivalent in the WBS Failure & Recovery module (Ref: UC_4.9.1–UC_4.9.4). This state is N/A for SIM — it only applies once the trader has been promoted to LIVE (Source: BA confirmation, 2026-08-10, QnA_init_docs.md QN-4.8.1-01).

BR_4.8.1.2: Dial Scale — Hard Stop Loss to Profit Target

On load, frontend calls GET /current-level-detail, which returns the trader's Market_Loss_When_Stopped and Profit_Target for their current level (Source: BA confirmation, 2026-08-10, QnA_init_docs.md QN-4.8.1-03):

• Left end (minimum): −Market_Loss_When_Stopped (Hard Stop Loss threshold). Example: Stop = $1,250 → left end = −$1,250.
• Right end (maximum): +Profit_Target. Example: Target = $1,875 → right end = +$1,875.

Arc rendering/scaling mechanics for these two endpoints (physical zero anchor, dual-domain needle mapping, tick marks, absolute end labels) are defined in BR_4.8.1.6, not repeated here.

BR_4.8.1.3: Needle — Live Net PnL, Always Reflects Actual Current-Level Data

The needle position, and the live dollar value displayed below it, both track the trader's actual current Net PnL for their current level — Unrealized PnL + Realized PnL, equivalently equity − allocated_capital (the starting capital allocated for the current level). This is a real-data requirement, not merely a "last event received" display: the value shown must at all times equal the trader's true current Net PnL for that level, regardless of whether a new position was just opened/closed or not — it is never a placeholder, a zeroed default, or a value that only updates when something changes.

• While the trader is actively on the Overview screen: the value streams live over the ACCOUNT_METRICS WebSocket channel (Source: BA confirmation, 2026-08-10, QnA_init_docs.md QN-4.8.1-03; event throttle: RFQ_ Stack Trading Prop Tech V7.pdf §3.2, ACCOUNT_METRICS, 1000ms).
• On landing/re-landing on the Overview screen (fresh page load, F5/hard reload, or a trade closes without producing a visibly distinct WS fluctuation): the needle and dollar value must still show the trader's real, correct current Net PnL immediately — even though no new ACCOUNT_METRICS event or new position has yet been pushed over the socket to trigger a visual update. The display is never allowed to sit blank, stale-to-zero, or otherwise out of sync with the actual current-level figures while waiting on the next tick.

BR_4.8.1.4: Per-State Left/Right Labels

Two persistent text labels sit beside the dial — bottom-left and bottom-right — and change content depending on the active state (Ref: BR_4.8.1.1) (Source: wireframes listed in Section 1):

• Starting point: Left = "Stop Loss Breach" heading + "Defense unlocked at Lvl. 9" sub-line (a static reminder of the LIVE-only Defense Protocol unlock level, shown even though N/A on SIM). Right = "Promotion: Level [N]" + "Est. Bonus $[amount]" — [N] is the next level (current level + 1) and [amount] is that level's Bonus_Paid_To_Trader, both looked up directly from Table A (Forex) / Table B (Futures), per the trader's asset class, for the next level (same next-level concept as the Level Progression widget, Ref: UC_4.8.2 §BR_4.8.2.2). This is a direct table lookup value — no tooltip is shown for either the next-level number or the bonus amount (Source: BA confirmation).
• Level Up: Right label changes to "Level [N] Unlocked!" + "$[amount] Bonus Transmitting". Left label unchanged.
• Breached (Account Disabled): Left label changes to "Stop Loss Breached" + "Account Disabled". Right label's value visually de-emphasizes (promotion no longer applicable this cycle) — exact interaction rule pending confirmation.

BR_4.8.1.5: Breached (Account Disabled) State — Display Only, Backend Flow Owned Elsewhere

When a LEVEL_STOP_BREACH event is received, the dial transitions to the "Breached (Account Disabled)" state — needle locked at the bottom/left, left label per BR_4.8.1.4. Per wireframe, the rest of the Overview screen (Position Monitor, The Pulse, Equity Curve, Profit Factor, Win Rate, The Desk Manager, Level Progression) turns desaturated (Frosted Glass) while the PnL Gauge itself remains in normal focus, as the primary indicator of the breach. This UC describes only the gauge's display behavior at this state; the full backend flow (Atomic Kill Switch, position flattening, account lock, Frosted Glass full-page effect) is owned by UC_4.9.2 — Hard Breach, Level Stop and is not repeated here.

BR_4.8.1.6: Center Value Precision & Dual-Domain Arc Rendering (reused verbatim by LIVE, Ref: UC_4.12.2 BR_4.12.2.2)

Governs how the arc built from the two endpoints in BR_4.8.1.2 is rendered, and how the live center value from BR_4.8.1.3 is formatted. This rule is UI-rendering scope only — it does not change either endpoint's underlying value or the needle's real-data correctness requirement (BR_4.8.1.3).

1. Full precision (whole dollars), no abbreviation: the center Net PnL value is shown as the exact dollar amount with comma thousands separators, cents omitted (e.g. $1,875, not $1,875.00). Abbreviated notation (1.8K, 1M) is never used, regardless of magnitude. This is a deliberate exception to CR-11 (which mandates 2 decimal places) — CR-11's decimal-display rule does not apply to this one field; CR-11's thousands-separator and hover-tooltip (full value) rules still apply.
2. Dynamic font scaling: if the formatted value (up to 7 digits) overflows the center display's container, the frontend shrinks the text via CSS scaling, down to a floor of 50% of its original size, to fit within container bounds.
3. Physical zero anchor & color split: the $0 mark is always rendered at the exact physical (visual) center of the gauge arc, regardless of the data-value asymmetry between the two endpoints (Profit Target and Hard Stop Loss are not equal magnitudes — Ref: BR_4.8.1.2). The red (loss) zone and green (profit) zone meet exactly at this physical center point — the color split is a rendering/visual boundary, not a data-value boundary.
4. Dual-domain needle mapping: because the two endpoints are asymmetric in magnitude while $0 is fixed at the physical center, the needle position cannot use one single linear scale across the whole arc. The frontend calculates needle position using two separate interpolation domains:
   • Negative Net PnL [−Market_Loss_When_Stopped, 0] maps onto the left half of the arc [leftmost point, center].
   • Positive Net PnL [0, +Profit_Target] maps onto the right half of the arc [center, rightmost point]. Each half has its own dollars-per-degree (or dollars-per-pixel) rate — the two halves are not proportionally equivalent.
5. Dynamic tick rendering: by default, 4 inner tick marks render on the right (profit) side, with proportionally fewer on the left (loss) side, using clean interval rounding (nearest hundred or thousand). If tick-label character counts crowd the arc at higher funding levels, the frontend reduces to 3 inner tick marks per side to preserve readability.
6. Absolute bounds: the rightmost label on the arc always displays the exact current Profit_Target; the leftmost label always displays the exact current Market_Loss_When_Stopped — both full precision, never rounded or abbreviated (same formatting as point 1).

(Source: Client description, relayed by user, BA session, 2026-08-31.)

8. Screen Description

---

Changelog