AI-native quantitative trading platform — research, backtest, execute, manage risk, and collaborate with controlled agents, all from one operator console.
QuantPilot is a platform skeleton and operating surface for controlled quantitative trading workflows, not a production unattended trading bot.
| Domain | What It Does |
|---|---|
| Research & Strategy | Strategy catalog, event-driven backtest engine (Sharpe, max drawdown, win-rate), evaluation, comparison, and governance |
| Execution | Plan → approve → submit → reconcile → recover lifecycle, broker-event ingestion, queue-based operations console |
| Risk | Live VaR/CVaR/Beta/HHI analytics, approval boundaries, policy actions, risk-parameter tuning panel |
| Agent Collaboration | Session → intent → plan → analysis → action handoff pipeline, daily-run loops (pre-market / intraday / post-market), ask-first queue |
| Real-Time Push | SSE state stream with exponential-backoff reconnect; polling drops to 15 s fallback |
| Auth & Security | JWT (HS256, 8h), AES-256-GCM broker key encryption at rest, workspace-aware RBAC |
| Operations | Monitoring, incidents, audit trail, backup/restore, integrity checks, SQLite WAL persistence |
| Charts | lightweight-charts v5 — equity curve, candlestick, signal bar |
| UX Extras | Cmd+K command palette, approval drawer, toast notifications |
- Node.js ≥ 20
- npm ≥ 10
npm install
# Start all three processes (separate terminals)
npm run dev # Web console → http://localhost:8080
npm run gateway # API gateway → http://localhost:8787
npm run worker # Background workerFor real broker or LLM integration, copy .env.example to .env and configure providers. Validate with:
npm run check:runtime-env -- --env-file .envKey env vars:
| Variable | Purpose |
|---|---|
JWT_SECRET |
HS256 signing key (min 32 chars) |
BROKER_KEY_ENCRYPTION_KEY |
64-char hex for AES-256-GCM |
DEMO_USERNAME / DEMO_PASSWORD |
Login credentials (admin / changeme) |
USE_HONO |
Set true for Hono gateway layer |
┌─────────────────────────────────────────────────────┐
│ apps/web React 18 SPA (Vite, VE styles) │
├─────────────────────────────────────────────────────┤
│ apps/api Node.js API gateway (ESM + tsx) │
├─────────────────────────────────────────────────────┤
│ apps/worker Background task runner │
├─────────────────────────────────────────────────────┤
│ packages/ │
│ ├── trading-engine Strategy, backtest, risk │
│ ├── task-workflow-engine Workflow orchestration │
│ ├── control-plane-runtime Runtime context & fanout │
│ ├── control-plane-store Persistence (file / SQLite) │
│ ├── llm-provider Provider-agnostic LLM │
│ ├── shared-types Cross-package contracts │
│ └── db SQLite adapter + Drizzle │
└─────────────────────────────────────────────────────┘
- Research — strategy catalog → backtest → evaluation → governance → execution handoff
- Execution — plan → broker event → reconciliation → compensation → incident linkage
- Middleware — risk workbench + scheduler workbench → reviewed actions → control-plane fanout
- Agent — prompt → intent → plan → analysis → handoff → approval → daily-run cycle
npm run dev # Vite dev server (HMR)
npm run gateway # API gateway
npm run worker # Background worker
npm run test:web # Vitest (frontend)
npm run test:api # node --test (API)
npm run test:engine # Workflow engine
npm run test:runtime # Runtime
npm run test:control-plane # Store layer
npm run test:worker # Worker
npm run typecheck # tsc --noEmit
npm run build # Production build
npm run verify # Full pipeline (all of the above)npm run verify runs sequentially:
- Workspace & lockfile integrity
- Documentation consistency
- Runtime env checks
- Lint (Biome)
- All test suites (control-plane → runtime → engine → API → worker → web)
- TypeScript typecheck
- Production build
A pre-push git hook runs verify automatically.
| Layer | Choice |
|---|---|
| Language | TypeScript 5 (TS-only first-party source) |
| Frontend | React 18 + react-router-dom 6 |
| Build | Vite 5 + vanilla-extract |
| Backend | Node.js ESM + tsx |
| Test | Vitest + node --test |
| Package Mgr | npm workspaces |
quantpilot/
├── apps/
│ ├── api/ API gateway
│ ├── web/ React SPA
│ │ └── src/
│ │ ├── app/ Shell, global styles
│ │ ├── components/ Shared UI (charts, command-palette, toast, approval-drawer)
│ │ ├── modules/ Domain modules (agent, console, research, risk, permissions)
│ │ ├── pages/ 9 route pages
│ │ ├── services/ API client layer
│ │ ├── store/ TradingSystemProvider
│ │ └── hooks/ useOhlcvData, useSSE
│ └── worker/ Background tasks
├── packages/ Shared engines & contracts
├── docs/ Architecture, ops, deployment
├── scripts/ Tooling & CI helpers
└── CONTRIBUTING.md
| What | Where |
|---|---|
| Web app | apps/web/src/app/App.tsx |
| Dashboard | apps/web/src/pages/console/DashboardConsole.tsx |
| State provider | apps/web/src/store/trading-system/TradingSystemProvider.tsx |
| API server | apps/api/src/main.ts |
| Worker | apps/worker/src/main.ts |
| Trading engine | packages/trading-engine/src/runtime.ts |
| Backtest engine | packages/trading-engine/src/backtest/index.ts |
| Control-plane | packages/control-plane-runtime/src/index.ts |
| Workflow engine | packages/task-workflow-engine/src/index.ts |
| Document | Purpose |
|---|---|
| Contributing Guide | Dev workflow, PR rules |
| Operations Handbook | Backup, restore, incidents |
| Deployment Guide | Build, env, deploy checklist |
| Migration Runbook | Control-plane schema changes |
| Project Structure | Detailed module map |
| Layered Architecture | Design philosophy |
The staged delivery roadmap (Stages 1–7) is closed. Stage closeout documents remain as architecture references and contract baselines enforced by verify:
Stage 1 · Stage 2 · Stage 3 · Stage 4 · Stage 5 · Stage 6 · Stage 7
- Browser never holds real broker credentials
- Remote order placement goes through the server gateway only
- Agents cannot place real trades directly
- Risk and approval controls cannot be bypassed
- This is not a production unattended live-trading deployment