# Multi-Broker Spread Platform — Super-Admin 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 the platform Super-Admin."*
> The AI will answer using only the information here.

---

## What the platform is
The Multi-Broker Spread Platform shows the **spread** (bid–ask gap) for many
instruments across many brokers in real time, side by side, and records the
history for charting and analysis. It is **multi-tenant**: each customer is a
**company**, fully isolated — no company can see another's brokers, symbols,
history or users, even if they use identical broker or symbol names.

## Your role: Super-Admin (platform owner)
You run the whole platform. On top of full admin powers in your own company, you
manage **all companies** on the **🏢 Companies** page and can see/verify the
**audit log across all companies**. Pages: Home, Live, History, Analytics, Admin,
Users, Audit, **Companies**, Account, Help.

## Roles & isolation (the model)
- **Viewer** — read-only dashboards/history for their company.
- **Admin** — manages their own company's brokers, symbols, users, history.
- **Super-Admin (you)** — creates/manages companies; cross-company audit; admin
  powers in your own company too.
Every data query is scoped to the caller's company; access is enforced on the
server, not just hidden in the UI. A viewer or admin literally cannot reach
another company's data or the Companies page.

## Companies page (🏢) — your main tool
Each row is a company; the columns show Company, Admin email, Status, Last login,
and Users/Brokers/Symbols counts, plus Brokers online/total for at-a-glance
health.
- **Create a company:** enter a name + the email and starting password for its
  first admin. That admin then adds their own team. (Controlled onboarding — no
  open sign-up.)
- **Details (▸):** expand a company to see its users (and each one's last login),
  every broker's live status and last tick, ticks recorded in 24h, and active
  users in 7 days — plus a link to that company's audit.
- **👁 View as:** open the dashboard signed in as that company's admin to see
  exactly what they see (best for troubleshooting). A banner stays on screen;
  click **Exit** to return to your own account. Logged in the audit.
- **Pause / Resume:** suspend a whole company — nobody there can log in and live
  sessions stop within ~10 seconds. **No data is deleted**; Resume restores
  everything. You can't pause your own company, and you're never locked out.
- **Rename** (✎ on the name) and **change the admin email** (✎ in the column).
- **🔑 Reset password:** set a temporary password on the company's primary admin
  (or auto-generate one); it shows you their email + the temp password to relay.
- **📝 Notes:** private free-text notes per company (plan, contact, billing…),
  visible only to you; a 📝 icon marks companies that have notes.
- **Delete:** permanently removes the company, its users, brokers and symbols.
  Recorded tick history is kept but orphaned. Cannot be undone — prefer Pause if
  you might restore access later.
- **🗓 History-deletion log** (button on the page): opens the audit filtered to
  history deletions across all companies — see exactly who wiped data and when.

## Audit & tamper-evidence (🛡️)
The Audit page records logins (and failures) and every broker/symbol/user/company
change with who did it. As super-admin you see **every company**. The log is
**append-only and hash-chained** (each entry's hash depends on the previous,
keyed by a server secret), so any later change, deletion or reordering of a past
entry is detectable. Press **🔐 Verify integrity** to check the whole chain
end-to-end ("intact" or "tampering detected at #X"). This is useful if, say, a
company admin wipes their own history and later disputes who did it — admins can't
edit or delete audit entries.

## Security model (so you can answer "is it safe?")
- Passwords are **hashed** (one-way PBKDF2) — never stored or shown in clear.
- Broker credentials (MT5 passwords, cTrader secrets) are **encrypted at rest**.
- Secrets live in a private `.env`, never in the code.
- **Login rate-limiting** throttles brute-force attempts (per email and per IP).
- **Sessions** are long-lived but admins can force-log-out any user; a permanent
  session option exists for 24/7 screens.
- **Audit** is tamper-evident (above).
- Known item to finish before exposing the backend publicly: lock the worker's
  internal endpoints with `WORKER_API_KEY` and put the site behind HTTPS/TLS.

## Everything admins/viewers can do (you can too)
- **Admin page:** add/edit brokers (MT5/API/cTrader), symbols, per-broker name
  mappings, API presets, test API connections, delete old history (incl.
  "Everything" via typing `DELETE ALL`), orphan cleanup.
- **Users page:** add (Viewer/Admin), reset password, force log-out, make
  permanent session, delete.
- **Live:** Matrix/List, best=green/worst=red, highlight vs filter, reorder,
  metric (points/raw), class filter, full screen, pinned header, source badges
  (mt5 green / api blue / ctrader violet / sim).
- **Alerts (⏱ Stall/surge monitor on Live):** *Stall* (feed went quiet) modes —
  **Average gap + grace** (adaptive), **Average gap (no grace)** (most
  sensitive), **Fixed idle limit** (plain timeout). *Surge* (spread blow-out) —
  auto spike detection + optional "> X points". Independent broker/symbol scopes
  (a cell is watched only if both selected; ⏱/⚡ marks). Banner + beep (surge
  higher, stall lower) + amber/red mark; sound selectable incl. **None (visual
  only)**; **🔔 Test alert** demos it; **📋 Alert log** records each; per-browser.
- **History:** range + brokers/symbols + bucket (Auto or fixed) + Log/Linear +
  ⬇ Excel.
- **Analytics:** per-broker, time-of-day, weekday, sessions, arbitrage windows,
  correlation; **🤖 Ask an AI** (Anthropic/Claude or OpenAI-compatible, your own
  key, used once, never stored).

## Onboarding a broker (incl. cTrader)
- **MT5:** needs a Windows machine with that broker's terminal logged in + the
  worker running.
- **API:** pick a preset, add the key, Test, Enable.
- **cTrader:** register an Open API app (Client ID/secret), get an access token,
  add a CTRADER broker with Host = Demo/Live, map symbols to cTrader's exact
  names. For real (live) customers use a **production** token and Host = Live.

## Troubleshooting & FAQ (Super-Admin)
- **A company's brokers show offline.** Use **👁 View as** to see their setup, or
  expand their row to check per-broker status/last tick. MT5 needs their terminal
  running on their machine.
- **A user can't log in.** Check the company isn't **Paused**; if they forgot
  their password, use **🔑 Reset password** (admin) or have their admin reset a
  viewer.
- **Verify nobody tampered with the audit.** Audit page → **🔐 Verify integrity**.
- **Pause vs Delete a company.** Pause = reversible suspension, no data loss.
  Delete = permanent removal (history orphaned). Prefer Pause unless you're sure.
- **Can a company see another company's data?** No — strict per-company
  isolation, server-enforced.
- **Page looks old after an update.** Hard-refresh; the version is in the top bar.
- **cTrader errors:** `CH_CLIENT_AUTH_FAILURE` = wrong/cut-off Client ID or
  secret; `CH_ACCESS_TOKEN_INVALID` = stale token (regenerate kills the old one,
  paste the newest, don't regenerate again); "no quotes" = symbol names don't
  match cTrader's exact names.