docs/FRONTEND_GUIDE.md

Frontend Guide

File and runtime

The entire Futures dashboard UI is packaged in:

hermes_overlay/tools/templates/hermes_futures_desk_luxury.html

The router reads this file at request time from its installed tools/templates directory and serves it at /futures. Do not add a second frontend server, bundler process, or port.

Design system

The UI uses an Obsidian & Gold workstation theme with a light-theme option. Operational values use readable sans-serif/monospace styling. Decorative serif/italic styling is limited to headings and visual accents.

Responsive modes cover desktop, tablet, and mobile. prefers-reduced-motion is respected.

Main UI regions

• fixed/collapsible navigation and local market lists;
• command deck with symbol, risk, Optional AI context switch, Analyze, and Paper Execute controls;
• selected-market header and chart;
• market diagnostics and field provenance;
• decision, score, risk approval, and execution mode;
• trade-plan geometry and execution checklist;
• signal reasons and components;
• Paper account and positions;
• datasource health and technical diagnostics;
• Telegram operational status;
• local activity/history and export actions.

API usage

The helper uses:

fetch(url, {
  credentials: 'same-origin',
  cache: 'no-store'
})

Primary calls:

GET  /api/futures/status
GET  /api/futures/symbols
GET  /api/futures/positions
GET  /api/futures/market
GET  /api/futures/trade-plan
GET  /api/futures/signals
GET  /api/futures/advisory
GET  /api/futures/activity
POST /api/futures/analyze
POST /api/futures/paper/execute
GET  /api/telegram/status

The V6 page router also lazy-loads dedicated read routes for trade plan, signals, optional AI context (advisory), and server activity. These requests are authenticated, use cache: 'no-store', and never fabricate fallback trading values when a route is empty or unavailable. The trade-plan page renders an authority contrast panel (emerald deterministic lane vs violet advisory lane) when data is present.

CSRF bootstrap uses GET /api/futures/csrf-token before POST mutations.

Refresh behavior

Default intervals:

• clock and age labels: 1 second;
• status and positions: 5 seconds while auto-refresh is enabled and page is visible;
• market data: 15 seconds;
• Telegram status: 60 seconds.

When the page becomes visible again, status and market data refresh if automatic refresh is enabled.

Chart behavior

Supported intervals:

1m 5m 15m 1h

Supported candle limits:

60 120 240

Modes:

• Candles;
• Line;
• optional volume bars.

The chart is an inline SVG and uses only candles returned by the market endpoint. Crosshair, OHLCV legend, tooltip, current-price reference, price labels, visible high/low, range position, and last-candle age are derived from the returned series.

No visual interpolation or fallback is permitted to create production candles.

Display-only diagnostics

The UI calculates visible trend, average candle range, relative last-candle volume, realized variation, last-candle direction, and range position from the real returned candles. These values are explicitly informational and must never change:

LONG / SHORT / NO_TRADE
risk approval
noTradeGuard
Entry / SL / TP
leverage
quantity
execution eligibility

Local browser state

The UI stores only convenience preferences/history in localStorage.

Known keys:

hermes_watchlist
hermes_recent_markets
hermes_auto_refresh
hermes_compact
hermes_motion
hermes_glow
hermes_ui_scale
hermes_sidebar_collapsed

Watchlist, recent markets, local analysis history, and workspace activity use Hermes-prefixed local keys defined in the template. They are not synchronized to the server and are not trusted for execution.

Keyboard shortcuts

Key	Action
/	Focus and select symbol search.
A	Run analysis when not already analyzing.
R	Manual refresh.
D	Toggle display density.
T	Toggle theme.
?	Open shortcut help.
Escape	Close overlays/help.

There is deliberately no keyboard shortcut for Paper Execute.

Analysis state rendering

Use the server result to set one of:

NOT_ANALYZED
ANALYZING
LONG
SHORT
NO_TRADE
ANALYSIS_FAILED
STALE
API_UNAVAILABLE

Important rules:

• initial state is “Waiting for analysis,” not NO_TRADE;
• HTTP/network failure is ANALYSIS_FAILED or API_UNAVAILABLE;
• score is “Unavailable” when components do not exist, not numeric zero;
• expiry is prominent only for a valid directional plan;
• rejected/incomplete analysis is not presented as executable;
• changing symbol or risk invalidates the current browser plan;
• server state remains authoritative.

Execute availability

The button is disabled unless the latest browser plan mirrors all required server fields. The UI displays a concrete disabled reason such as:

Run analysis first
No directional plan
Risk approval failed
noTradeGuard active
Market-only symbol
Plan expired
Symbol changed
Risk profile changed
Plan already executed
Required Futures fields unavailable

These checks improve UX but do not replace backend revalidation.

Adding a UI feature safely

1. Reuse existing API fields or add an additive backend field.
2. Render missing values as Unavailable, never zero or fabricated content.
3. Keep browser calculations labeled display-only.
4. Do not add another Execute path or shortcut.
5. Invalidate plan display when relevant controls change.
6. Keep DOM IDs unique and update static ID checks.
7. Preserve responsive and reduced-motion behavior.
8. Do not display raw provider errors or secrets.
9. Verify Console and Network in an authenticated deployed session.