# Multi-Broker Spread Platform — Viewer Guide (AI assistant reference)

> **HOW TO USE THIS FILE:** Paste this whole document into any AI chatbot
> (ChatGPT, Claude, Gemini, etc.), then ask your question. Start with:
> *"Use the document below to answer my questions about the Spread Platform. I am a Viewer."*
> The AI will answer using only the information here.

---

## What the platform is
The Multi-Broker Spread Platform connects to several brokers at once and shows,
for every instrument, the **spread** — the gap between the **bid** (sell) price
and the **ask** (buy) price — in real time, side by side. A **tighter** spread is
cheaper to trade; a **wider** one is more expensive. It also records spread
history so you can chart and analyse it later.

Everything is split by **company**: you only ever see your own company's brokers,
symbols, history and data. Other companies' data is completely private.

## Your role: Viewer (read-only)
As a Viewer you can **see** the dashboards and history but **cannot change**
anything. You don't see the Admin, Users, Audit or Companies pages — those are
for admins. If you need a broker added, a symbol changed, or a new login, ask
your company's **admin**.

## Signing in & your account
- **Log in** with your email and password at the login screen.
- Sessions stay signed in (no automatic time-out). An admin can log you out
  remotely if needed.
- **Change your password:** click your email (top-right) → **Account** → enter
  your current password and a new one.
- **Forgot your password?** Ask your admin to reset it; they'll give you a
  temporary one to log in with, then change it under Account.
- **Permanent session:** for an always-on screen (e.g. a wall display), an admin
  can mark your account so it never logs out.
- **"Your session was ended" / suddenly signed out:** an admin logged your
  account out, or your whole company's access was paused. Sign in again; if you
  can't, contact your admin.

## The pages you can use
- **Home** — quick links and whether the backend is online.
- **🔴 Live** — the real-time spread board with alerts and full-screen mode.
- **📊 History** — query and chart recorded spreads, export to Excel.
- **📈 Analytics** — broker comparison, time-of-day patterns, and AI analysis.
- **🔑 Account** — change your own password.
- **❓ Help** — the in-app help and FAQ.

## Live view (real-time spreads)
- **Matrix vs List:** Matrix shows symbols as rows and brokers as columns (blank
  where a broker doesn't offer a symbol). List shows one flat row per
  broker/symbol with bid, ask and spread. Switch with the Matrix / List buttons.
- **Colours:** green = the best (tightest) spread for a symbol, red = the worst,
  when 2+ brokers quote it.
- **Highlight vs Filter:** pick symbols and/or brokers. *Highlight* emphasises
  them and dims the rest; *Filter* hides everything else.
- **Reorder:** in Matrix view use ▲▼ to move symbols and ◀▶ to move brokers; the
  List view follows the same order. Click a column header to sort instead.
- **Metric:** show spread in points or as the raw spread.
- **Asset-class filter:** quickly show just Forex, Metals, Indices, Crypto, etc.
- **Full screen:** the ⛶ button blows the grid up to fill the screen (Esc to
  exit) — handy for a wall display.
- **Pinned header:** the column headers and symbol column stay fixed while you
  scroll, so labels are always visible.
- **Broker badges:** each feed is tagged by source — **mt5** (green), **api**
  (blue), **ctrader** (violet), **sim** (simulation).
- **Theme:** top-right switcher — System, Light or Dark.

## Stall & surge alerts (on the Live page)
Open them with the **⏱ Stall/surge monitor** button on the Live toolbar. Both
are independent and both save their settings in **your own browser** (per
viewer). You can use these as a Viewer.

**Stall alert ⏱ — a feed went quiet.** Warns when a symbol *stops* changing price
(a frozen or broken feed). It learns each symbol's normal pace. Threshold modes:
- **Average gap + grace** — adaptive: alerts when idle time exceeds that symbol's
  own average update gap *plus* your grace seconds. Best when symbols update at
  very different rates.
- **Average gap (no grace)** — alerts as soon as idle exceeds the symbol's
  average; the most sensitive (fires more often).
- **Fixed idle limit** — a plain timeout: alerts after the same number of idle
  seconds for every symbol (no learning needed).

**Surge alert ⚡ — a spread blow-out.** Warns when a spread suddenly jumps
abnormally *wide* (a market event). Uses automatic per-symbol spike detection;
you can optionally add a hard "alert if spread > X points" limit.

**Setting them up:**
1. Tick **Enable stall alert** and/or **Enable surge alert** (independent).
2. Each has its **own brokers and symbols** to watch — a cell is monitored only
   when **both** its broker and its symbol are selected in that section. A ⏱
   (stall) or ⚡ (surge) marker appears on the watched rows.
3. Set the grace / idle limit (stall), the surge points limit (surge; 0 = auto
   spike only), and **Keep mark for** (how long the mark and banner linger).

When an alert fires you get a **banner** at the top of the grid, a **beep** (a
higher tone for surge, lower for stall), and the cell is marked — **amber for a
stall, red for a surge**. Pick the **Alert sound** in the dialog (Beep, Siren,
Warble, Chime, Buzzer, or **None (visual only)** for a silent alert). Use the
**🔔 Test alert** button to fire a full demo. The **📋 Alert log** keeps a record
of every alert (type, broker/symbol, time); **Clear log** empties it.

## History
- Pick a **time range**, the **brokers** and **symbols** (no selection = all),
  then **Query**. Times are shown in Cyprus time.
- **Bucket:** each point is an average over a window. Leave it on **Auto** (sized
  to your range: 1 day → 1-minute, 1 week → 10-minute, 1 month → 30-minute) or
  pick a fixed size.
- The table shows average bid/ask, average/min/max spread, and a tick count.
- **Scale:** the chart defaults to a **Log** axis so big spreads (e.g. BTCUSD)
  and tiny ones (FX) are all visible together; switch to **Linear** for a single
  symbol. Click **⬇ Excel** to download the result.
- Tip: selecting only the brokers/symbols you care about makes the chart clearer.

## Analytics
Pick a range and press **Analyze data**, then choose a **Focus symbol**. You get:
average spread by broker (tightest→widest), spread by time of day, who quotes
high vs low, spread vs the cross-broker average, per-broker statistics, spread by
weekday and by trading session, arbitrage windows, and broker correlation.

**🤖 Ask an AI to analyse this:** choose a provider (Anthropic/Claude or
OpenAI-compatible), optionally a model, paste **your own API key** and a
question, then **Analyse**. It sends the computed summary (not raw ticks) to the
provider; your key is used once and never stored, and it uses your own API
credits.

## Troubleshooting & FAQ (Viewer)
- **A broker's dot isn't green / shows offline.** The feed for that broker is
  down — tell your admin. (MT5 brokers need their terminal running and logged in
  on the company's machine.)
- **Prices show but say "stale".** No fresh tick arrived recently; usually a
  clock or connection issue on the data-collector machine — an admin fixes it.
- **I can't see the Admin / Users pages.** That's by design — those are
  admin-only. As a Viewer you have read-only access.
- **A page looks old after an update.** Hard-refresh (Cmd+Shift+R or
  Ctrl+Shift+R); the version number is in the top bar.
- **The alert doesn't beep.** Browsers only allow sound after you interact with
  the page — tick the enable box or press 🔔 Test alert. Check volume and that
  the tab isn't muted.
- **Do we need a screen left on to collect history?** No. Recording happens on
  the server side continuously; an always-on screen is only for a live display.
- **Can I see another company's data?** No — data is private per company.