# Product specification (verbatim, 2026-10-21)

## Mission
Build a production-quality, self-hosted quantitative algorithmic trading research, backtesting, paper-trading, and execution platform for Kraken. The central product is **systematic algorithmic trading**, not a generic AI chatbot or bot-monitoring dashboard. Deliver a working full-stack web application, reproducible research pipelines, and tested trading services. Prioritize statistical validity, execution realism, capital preservation, security, and observability over speculative claims of profitability.

## Non-negotiable operating rules
- Begin in offline/backtest and paper-trading modes. Never place live orders unless the human owner separately configures credentials with trading permission, passes preflight checks, and explicitly activates live mode in the UI with a second confirmation.
- Do not request or display secret API keys in chat, logs, source control, or browser local storage. Store credentials server-side encrypted using environment-injected secrets or a secret manager. Use separate least-privilege Kraken API keys for market data, account read, and trading. Never enable withdrawal permission.
- Implement an independent risk gateway that every order must pass; no model, strategy, or agent can bypass it. Default-deny on stale data, connection loss, reconciliation failure, invalid order, or risk service outage.
- Do not claim any strategy is profitable without genuine out-of-sample evidence, realistic fees/slippage and reproducible reports. Do not manufacture results, prices, or historical data.
- Check current official Kraken Spot REST/WebSocket documentation for endpoint names, signing, rate limits, minimum sizes, precision, supported pairs, order types, and account jurisdiction. Make exchange capabilities discoverable, not hard-coded assumptions. No leveraged derivatives unless explicitly supported for this account and separately authorized.

## Deliverables
1. A deployable monorepo with web frontend, Python API, market-data ingestion, research engine, event-driven backtester, paper execution simulator, live execution adapter (disabled by default), risk engine, worker scheduler, PostgreSQL/TimescaleDB storage, Redis messaging, and monitoring.
2. A polished responsive web terminal: strategy laboratory, strategy comparison, market explorer, interactive candlesticks and order book, portfolio and risk dashboards, backtest explorer, paper-trading console, execution quality, live status, alerts, audit history, and configuration.
3. Working example strategies, unit/integration/property tests, Docker Compose, sample `.env.example`, architecture diagrams, API docs, operator runbook, and reproducible research notebooks.
4. A research report for each strategy showing economic hypothesis, universe, data coverage, parameters, in-sample and out-of-sample performance, uncertainty, implementation costs, and failure modes.

## Suggested technology
- Frontend: Next.js, TypeScript, Tailwind, shadcn/ui, TradingView Lightweight Charts or equivalent, TanStack Query, accessible data tables.
- Backend: Python 3.12+, FastAPI, Pydantic, asyncio, SQLAlchemy, PostgreSQL/TimescaleDB, Redis, background workers; typed APIs and WebSockets for streaming.
- Quant: NumPy, pandas/Polars, SciPy, statsmodels, scikit-learn, arch, cvxpy, optional PyTorch, LightGBM and XGBoost. Use libraries only where supported and tested.
- Observability: structured logs, Prometheus/OpenTelemetry, health checks, Grafana dashboards, alerting, correlation IDs, immutable order audit trail.
- Local-first Docker Compose deployment for Apple Silicon Macs; isolate services, benchmark performance, and support future horizontal scaling. Avoid unnecessary Kubernetes complexity.

## Quantitative strategy research — implement as plugins
Build a strategy SDK with standardized lifecycle: load data, calculate features, generate target positions/orders, estimate uncertainty, assess risk, execute in simulation, and report. Include:
- Trend following: time-series momentum, cross-sectional momentum, moving-average ensembles, volatility targeting, breakout signals.
- Mean reversion: z-score, Ornstein–Uhlenbeck, half-life estimation, regime filters, transaction-cost-aware entry/exit.
- Statistical arbitrage: Engle–Granger/Johansen cointegration, error-correction models, dynamic hedge ratios via Kalman filter, robust spread diagnostics, capacity and borrow/short constraints. If shorting is unavailable, demonstrate spot-feasible alternatives rather than assuming leverage.
- Market making: Avellaneda–Stoikov reservation price/spread model, inventory penalties, adverse selection, queue-aware fill models, latency and cancellation controls; explicitly distinguish simulation from real order-book priority.
- Volatility and regime: GARCH-family forecasting, realized volatility, change-point detection, hidden Markov models, regime-dependent risk budgets.
- ML forecasting: lagged tabular features with LightGBM/XGBoost, probabilistic forecasts, calibrated uncertainty, drift monitoring; optionally temporal deep learning with strong naive baselines.
- Portfolio construction: volatility targeting, inverse-volatility, hierarchical risk parity, mean–variance with shrinkage, CVaR optimization, robust constraints, turnover penalties.
- Execution: market/limit decision rules, TWAP, VWAP where volume profiles exist, participation caps, adaptive execution using spread/depth, post-trade implementation shortfall analysis.
- Optional reinforcement learning sandbox only after baseline strategies are implemented, with explicit non-stationarity and simulation-to-reality warnings. RL never directly controls live execution without independent risk gating.

## Data engineering and market microstructure
- Ingest official Kraken historical candles, trades, and streaming market data as available; document retention/coverage limitations. For deeper history use explicitly licensed external datasets with provenance.
- Persist raw immutable events and normalized bars/order books. Handle reconnects, sequence gaps, deduplication, timestamp normalization, corporate-like symbol changes, delistings, pair metadata, and exchange maintenance.
- Record best bid/ask, trades, spread, depth, imbalance, realized volatility, fees, and funding only when actually applicable. Track data quality metrics and missing intervals.
- Separate research snapshots from live streams; use event-time semantics, not wall-clock shortcuts. Prevent look-ahead bias from bar closing times and feature joins.

## Backtesting and validation standards
- Build an event-driven backtester with the same strategy and risk interfaces used by paper/live engines. Explicitly model exchange maker/taker fees, bid/ask spread, slippage, order sizing/rounding, minimum notional, partial fills, rejected orders, latency, and available depth.
- No same-bar execution on unavailable information. Respect data availability timestamps and order arrival times.
- Implement anchored/rolling walk-forward evaluation, purged/embargoed cross-validation when labels overlap, holdout periods, bootstrap confidence intervals, parameter sensitivity maps, and multiple-testing controls (e.g., deflated Sharpe/probability of backtest overfitting where appropriate).
- Benchmark against buy-and-hold, cash, simple momentum, and equal-risk strategies. Report CAGR/annualized return when valid, volatility, Sharpe, Sortino, max drawdown, Calmar, turnover, hit rate, profit factor, tail risk, exposure, capacity, fee drag, and trade-level distributions.
- Produce full experiment provenance: code commit, dataset version/hash, parameters, random seeds, evaluation window, cost assumptions, and reproducible artifacts. Never optimize on the final test set.
- Add Monte Carlo stress tests, block bootstrap, shuffled trades, spread widening, fee increases, exchange outage, sudden gaps, liquidity collapse, and correlated drawdowns.

## Risk and portfolio controls
- Enforce per-order and per-symbol size limits, max gross/net exposure, concentration, daily loss, rolling drawdown, portfolio VaR/CVaR guardrails, liquidity participation, max open orders, and minimum available cash.
- Circuit breakers for volatility spikes, data staleness, anomalous prices, excessive cancellations, clock drift, API errors, unexpected fills, and reconciliation mismatches.
- A global kill switch cancels eligible open orders and blocks new ones; describe what cannot be guaranteed during exchange outages.
- Reconcile exchange balances, orders and fills against the internal ledger; ensure idempotent client order identifiers and retry policies that cannot duplicate orders.
- Live activation requires owner confirmation, trading-key permission verification, risk-budget selection, small-size canary phase, and visible active-state banner. No unattended auto-enabling.

## Web app information architecture
- **Overview:** total equity, cash, realized/unrealized P&L, current exposures, risk status, active strategies, exchange connectivity.
- **Market Explorer:** symbol search, candles, depth, spread, volume, volatility, data-quality status.
- **Strategy Lab:** strategy catalog, hypothesis, editable validated parameters, feature visualization, launch backtests, compare runs.
- **Backtest Explorer:** equity/drawdown curves, rolling Sharpe, underwater chart, trade ledger, fees, slippage, sensitivity heatmaps, walk-forward folds, confidence intervals.
- **Portfolio Optimizer:** covariance estimation, target weights, constraints, rebalance simulation, turnover and stress scenarios.
- **Paper Trading:** real-time virtual positions, orders/fills, strategy state, simulated P&L and realistic fee model.
- **Execution Console:** order lifecycle, routing status, Kraken error codes, latency, reconciliation, cancel controls; live tab locked by default.
- **Risk Center:** limits, breaches, stress tests, circuit breakers, kill switch and immutable audit history.
- **Research Reports:** downloadable HTML/PDF summaries and machine-readable JSON/CSV artifacts.
- **Settings:** exchange credentials status (never expose secrets), API permissions, environments, alerts, access control, retention and backup.

## Development plan and acceptance criteria
Phase 1: Inspect repository, read current official Kraken docs, define architecture and threat model, create project skeleton and Docker Compose. Implement read-only exchange connection, pair metadata, candles, market streams, database and a functioning market dashboard. Include tests.
Phase 2: Implement event-driven backtester, realistic fee/fill engine, strategy SDK, momentum and mean-reversion baselines, research dashboard and reproducibility metadata. Prove no-lookahead behavior with tests.
Phase 3: Implement advanced strategies (cointegration/Kalman, GARCH/regimes, portfolio optimization, market-making simulation), walk-forward testing, stress scenarios and comparison reports. Mark strategies experimental until validated.
Phase 4: Implement paper-trading execution, reconciled simulated ledger, independent risk gateway, alerts, full observability, robust reconnects and failure injection tests.
Phase 5: Implement live Kraken adapter behind feature flags and owner-controlled activation. Test against mocks/sandbox capabilities if officially supported, then perform a documented small-size canary only after explicit user authorization. Never place live orders merely because the implementation is complete.

For each phase, produce runnable code, migrations, tests, documentation and screenshots if available. Execute tests, linting and type checking; fix failures. Do not stop at an architecture essay or static mockup. Record any unimplemented features and limitations honestly. Prioritize a robust end-to-end vertical slice before adding more models.

## Security and compliance
Use secure sessions, CSRF protections, rate limits, role-based permissions, encrypted secret storage, audit logs, dependency scanning, and HTTPS at deployment. Restrict API-key IPs where supported. Treat jurisdictional restrictions and Kraken account entitlements as runtime checks, not assumptions. Avoid custody/withdrawal workflows entirely.