# Backtesting and Replay v1 (Frontend)

## Scope
The dashboard provides a non-technical backtest runner and replay viewer for precomputed backtest results.
Replay controls are UI-only and never re-execute strategy logic.

## Feature Flags
- Build-time gate (optional):
  - `VITE_BACKTEST_ENABLED=true` enables backtest UI code paths.
  - If omitted, UI defaults to enabled.
- Runtime gates (authoritative, from backend `/api/config`):
  - `ENABLE_BACKTEST` (master switch)
  - `BACKTEST_CUSTOMER_ENABLED` (customer access switch)

Backtest UI entry points:
- Strategy Wizard final step (`Run Backtest`)
- My Strategies cards (backtest icon)
- Dedicated `Backtesting` tab (profile selector + runner)

Backtesting tab modes:
- `Single Run`: run one profile at a time and inspect full replay/dashboard output.
- `Compare Strategies`: select multiple profiles, run same replay window, and view ranked summary metrics with drill-down details.

Access behavior:
- Admin users can access when `ENABLE_BACKTEST=true`.
- Non-admin users can access only when both flags are true.
- In admin `Preview as Customer` mode, customer rules are applied.

## User Flow
- Configure symbols, timeframe, UTC date range, and source:
  - CSV
  - JSON / Replay JSON
  - Kraken historical source (read-only backend fetch)
- Submit to `POST /api/backtest/run`.
- View deterministic result payload: window metadata, assumptions, timeline, trades, and diagnostics.

## Replay Controls (UI-Only)
- `Play`
- `Pause`
- `Step`
- Speed: `1x`, `5x`, `20x`, `Instant`

Replay syncing behavior:
- Cursor timestamp advances through precomputed timeline points.
- Equity and drawdown charts show a synced cursor marker.
- Trades table highlights and auto-scrolls active trade rows.
- Insight text updates per timestamp (for example: no trade due to failed rule).

## Time-Window Semantics in UI
- Window is shown explicitly as `from -> to (UTC)`.
- Copy communicates that simulation is historical and read-only.
- End-of-window policy from backend is visible:
  - `OPEN_AT_END` (default)
  - `FORCE_CLOSE`
- `OPEN_AT_END` positions are displayed in a dedicated panel.

## Safety Messaging
UI explicitly states:
- No real or paper orders are placed.
- Backtests are deterministic simulations and not live guarantees.

## Localhost Enable/Test
1. Start backend and frontend dev servers.
2. Sign in as admin and open `Config` tab.
3. In `Backtest Access Control`:
   - Turn on `Enable Backtest Globally`.
   - Optionally turn on `Enable Backtest For Customers`.
   - Click `Save Backtest Flags`.
4. Open `Strategy Wizard` or `My Strategies` and run a backtest.
5. Optional validation:
   - Turn customer flag off and use `Preview as Customer`.
   - Confirm backtest entry points disappear and API run calls are blocked for non-admin views.