Simon Moisy
0c82c4f366
- Added FastAPI backend with core API endpoints for strategies, backtests, and data management. - Introduced Vue 3 frontend with a dark theme, enabling users to run backtests, adjust parameters, and compare results. - Implemented Pydantic schemas for request/response validation and SQLAlchemy models for database interactions. - Enhanced project structure with dedicated modules for services, routers, and components. - Updated dependencies in `pyproject.toml` and `frontend/package.json` to include FastAPI, SQLAlchemy, and Vue-related packages. - Improved `.gitignore` to exclude unnecessary files and directories.
9.0 KiB
9.0 KiB
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
- Background:
- 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
- Frontend requests available strategies via
GET /api/strategies - User configures parameters and clicks "Run Backtest"
- Frontend sends
POST /api/backtestwith configuration - Backend instantiates strategy, runs
Backtester.run_strategy(), saves result - Backend returns serialized results (equity curve as JSON array, trades, stats)
- Frontend renders charts and metrics
- 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
StaticFilesor 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