# PRD: Interactive Backtest UI

## 1. Introduction / Overview

Lowkey Backtest currently operates exclusively through a CLI. This project adds an interactive web-based UI that allows users to:

- Run backtests with existing code-defined strategies
- Adjust strategy parameters without editing code
- Compare multiple backtest runs visually
- Analyze performance through interactive charts and metrics

The UI will use **FastAPI** for the backend API and **Vue 3** for the frontend, styled with a dark theme inspired by QuantConnect.

---

## 2. Goals

| # | Goal | Success Metric |
|---|------|----------------|
| G1 | Run backtests from UI | User can select strategy, symbol, parameters and execute backtest |
| G2 | Visualize results | Equity curves, trade markers, and metrics displayed interactively |
| G3 | Compare runs | Side-by-side comparison of 2+ backtest results |
| G4 | Parameter experimentation | Adjust parameters via form inputs, re-run, and compare to previous |
| G5 | Self-hostable | Deployable on user's Arch-based NAS with minimal configuration |

---

## 3. User Stories

### US1: Run a Backtest
> As a trader, I want to select a strategy and configure its parameters in the UI so that I can run a backtest without using the terminal.

### US2: View Backtest Results
> As a trader, I want to see an interactive equity curve with trade entry/exit markers so that I can visually understand strategy performance.

### US3: Compare Parameter Changes
> As a trader, I want to compare two or more backtest runs side-by-side so that I can determine if a parameter optimization improves performance.

### US4: Quick Parameter Tweaking
> As a trader, I want to adjust strategy parameters (e.g., period, multiplier, SL/TP) via sliders or inputs and re-run the backtest so that I can iterate quickly.

### US5: Review Historical Runs
> As a trader, I want to see a list of previous backtest runs so that I can reload and compare past results.

---

## 4. Functional Requirements

### 4.1 Backend (FastAPI)

| # | Requirement |
|---|-------------|
| FR1 | `GET /api/strategies` - Return list of available strategies with their default and grid parameters |
| FR2 | `GET /api/symbols` - Return list of available symbols from local data |
| FR3 | `POST /api/backtest` - Execute a backtest with given strategy, symbol, timeframe, and parameters. Return results including portfolio stats, trades, and equity curve data |
| FR4 | `GET /api/backtest/{run_id}` - Retrieve a specific historical backtest result |
| FR5 | `GET /api/backtests` - List all saved backtest runs with summary metadata |
| FR6 | `POST /api/compare` - Accept multiple run IDs and return combined data for comparison |
| FR7 | `GET /api/data/status` - Return available data inventory (symbols, timeframes, date ranges) |
| FR8 | Results must be persisted (SQLite or JSON files) to allow historical retrieval |

### 4.2 Frontend (Vue 3)

| # | Requirement |
|---|-------------|
| FR9 | **Strategy Selector**: Dropdown to select strategy (rsi, macross, meta_st, regime) |
| FR10 | **Parameter Form**: Dynamic form fields based on selected strategy's parameters (inputs, sliders) |
| FR11 | **Symbol/Market Picker**: Select trading pair and market type (spot/perpetual) |
| FR12 | **Date Range Selector**: Pick start and end dates for backtest period |
| FR13 | **Run Button**: Execute backtest with loading state indicator |
| FR14 | **Equity Curve Chart**: Interactive line chart (Plotly.js) showing portfolio value over time with drawdown overlay (shaded area) |
| FR15 | **Trade Markers**: Overlay entry (green) and exit (red) markers on price/equity chart |
| FR16 | **Metrics Panel**: Display key stats (Total Return, Sharpe, Max DD, Win Rate, etc.) |
| FR17 | **Trade Log Table**: Sortable, filterable table of all trades |
| FR18 | **Run History Sidebar**: List of previous runs with quick-load action |
| FR19 | **Comparison View**: Select 2+ runs to overlay equity curves and compare metrics in a table |
| FR20 | **Dark Theme**: QuantConnect-inspired dark color scheme |

### 4.3 Comparison Features

| # | Requirement |
|---|-------------|
| FR21 | Overlay up to 5 equity curves on the same chart with different colors |
| FR22 | Metrics comparison table showing deltas between runs |
| FR23 | Highlight which run performed better for each metric |
| FR24 | Display parameter differences between compared runs |

---

## 5. Non-Goals (Out of Scope)

| # | Non-Goal |
|---|----------|
| NG1 | Strategy code editing in the UI (strategies are created in code editor) |
| NG2 | Live trading or paper trading integration |
| NG3 | Real-time market data streaming |
| NG4 | Multi-user authentication or access control |
| NG5 | Walk-Forward Analysis UI (may be added in future iteration) |
| NG6 | Data download management (use CLI for now) |

---

## 6. Design Considerations

### 6.1 Visual Style
- **Theme**: Dark mode only (similar to QuantConnect, TradingView dark)
- **Colors**: 
  - Background: `#1a1a2e` (deep navy)
  - Cards/Panels: `#16213e` 
  - Accent: `#0f3460` (muted blue)
  - Profit: `#00d26a` (green)
  - Loss: `#ff6b6b` (red)
  - Text: `#e8e8e8`
- **Typography**: Monospace for numbers/stats, clean sans-serif for labels
- **Layout**: Sidebar navigation + main content area

### 6.2 Component Library
- Consider Tailwind CSS for styling flexibility
- Plotly.js for charts (matches existing VectorBT ecosystem)
- Headless UI or Radix for accessible components

### 6.3 Responsive Design
- Primary target: Desktop (1920x1080+)
- Minimum supported: 1280x720
- Mobile not required

---

## 7. Technical Considerations

### 7.1 Architecture

```
lowkey_backtest/
  api/                    # FastAPI backend
    __init__.py
    main.py               # FastAPI app entry point
    routers/
      backtest.py         # Backtest endpoints
      strategies.py       # Strategy info endpoints
      data.py             # Data status endpoints
    models/
      schemas.py          # Pydantic request/response models
    services/
      runner.py           # Wraps existing Backtester
      storage.py          # Run persistence (SQLite)
  frontend/               # Vue 3 app (Vite)
    src/
      components/         # Reusable UI components
      views/              # Page-level components
      composables/        # Vue composition functions
      api/                # Axios API client
      assets/             # Styles, images
```

### 7.2 Data Flow

1. Frontend requests available strategies via `GET /api/strategies`
2. User configures parameters and clicks "Run Backtest"
3. Frontend sends `POST /api/backtest` with configuration
4. Backend instantiates strategy, runs `Backtester.run_strategy()`, saves result
5. Backend returns serialized results (equity curve as JSON array, trades, stats)
6. Frontend renders charts and metrics
7. Run is saved and appears in history sidebar

### 7.3 Dependencies

**Backend:**
- FastAPI
- Uvicorn (ASGI server)
- SQLAlchemy (run storage)
- Existing engine modules (Backtester, DataManager, etc.)

**Frontend:**
- Vue 3 (Composition API)
- Vite (build tool)
- Plotly.js (charts)
- Tailwind CSS (styling)
- Axios (API calls)

### 7.4 Deployment

- Development: `uvicorn api.main:app --reload` + `npm run dev`
- Production (NAS): 
  - Build frontend static files
  - Serve via FastAPI's `StaticFiles` or nginx
  - Run with systemd service

---

## 8. Success Metrics

| Metric | Target |
|--------|--------|
| Backtest execution via UI | Works for all 4 strategies |
| Result visualization | Equity curve + trades render correctly |
| Comparison view | Can compare up to 5 runs with overlaid equity curves |
| Run persistence | Historical runs survive app restart |
| Page load time | < 2s for dashboard |
| Backtest response time | Same as CLI (backend performance unchanged) |

---

## 9. Resolved Questions

| # | Question | Decision |
|---|----------|----------|
| Q1 | React or Vue for frontend? | **Vue 3** - simpler, sufficient for this use case |
| Q2 | Should the equity curve include drawdown overlay by default? | **Yes** - shaded area beneath equity curve |
| Q3 | How many historical runs to keep before auto-cleanup? | **Unlimited** - manual deletion only |
| Q4 | Should comparison support more than 2 runs? | **Yes** - support 3-5 run overlays |
| Q5 | Include WFA visualization in V1 or defer to V2? | Deferred to V2 |

---

## 10. Milestones (Suggested)

| Phase | Deliverable | Effort |
|-------|-------------|--------|
| **Phase 1** | FastAPI backend with core endpoints (strategies, backtest, history) | 2-3 days |
| **Phase 2** | Frontend scaffold with dark theme and strategy selector | 2-3 days |
| **Phase 3** | Backtest execution flow and results visualization | 3-4 days |
| **Phase 4** | Run history and comparison view | 2-3 days |
| **Phase 5** | Polish, testing, NAS deployment | 2 days |

**Total Estimated Effort**: 11-15 days

---

## Appendix: Reference Screenshots

*(QuantConnect-style inspiration)*

- Dark navy background with card-based layout
- Left sidebar for navigation and run history
- Main area split: configuration panel (top/left) + results (bottom/right)
- Charts with grid lines, legend, and interactive tooltips
- Metrics displayed in a compact card grid