learning_ai_invt_trdg/web/backtesting.md

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.