# TradeFinder Development Plan

## Vision

Automated crypto trading system for BTC/ETH perpetual futures with regime-adaptive strategy selection, risk management, and full transparency via web UI.

---

## Phase 1: Foundation (Current)

**Goal**: Core infrastructure, exchange connectivity, paper trading capability

### Milestone 1.1: Project Setup ✅
- [x] Repository structure
- [x] pyproject.toml with dependencies
- [x] Docker configuration
- [x] Environment template

### Milestone 1.2: Configuration & Core ✅
- [x] Pydantic settings with validation
- [x] Structured logging (structlog)
- [x] Error handling patterns

### Milestone 1.3: Exchange Adapter ✅
- [x] Abstract exchange interface
- [x] Binance USDⓈ-M Futures adapter
  - [x] Hedge mode (dual position side)
  - [x] Isolated margin per symbol
  - [x] Leverage configuration
  - [x] Order types: limit, stop-market
- [x] Testnet connectivity verification

### Milestone 1.4: Data Ingestion
- [x] REST OHLCV fetcher (historical via get_candles)
- [ ] WebSocket streams (real-time)
  - [ ] Kline/candlestick
  - [ ] Mark price (REST available)
  - [ ] Funding rate (REST available)
- [ ] DuckDB storage schema
- [ ] Data validation & gap detection

---

## Phase 2: Trading Logic

**Goal**: Regime detection, strategies, risk management

### Milestone 2.1: Regime Classifier
- [ ] ADX-based trend detection
- [ ] ATR% volatility measurement
- [ ] Bollinger Band width for squeeze detection
- [ ] Regime states: trending, ranging, high_volatility

### Milestone 2.2: Strategy Suite
- [ ] Base strategy interface
- [ ] Supertrend (trend-following)
- [ ] Squeeze Breakout (volatility expansion)
- [ ] Mean Reversion (range-bound)
- [ ] Grid logic (optional, later)

### Milestone 2.3: Risk Engine
- [ ] Position sizing from stop distance + risk%
- [ ] Per-trade risk limits (1-3%)
- [ ] Strategy allocation caps (25% max)
- [ ] Portfolio heat tracking

### Milestone 2.4: Order Manager
- [ ] Limit order entries with retry logic
- [ ] Stop-market circuit breakers
- [ ] Order state machine
- [ ] Fill tracking & slippage logging

---

## Phase 3: Optimization & Backtesting

**Goal**: Walk-forward optimization, performance measurement

### Milestone 3.1: Backtester
- [ ] Event-driven backtesting engine
- [ ] Realistic fill simulation (slippage, fees)
- [ ] Funding rate impact modeling
- [ ] Multi-symbol support

### Milestone 3.2: Optimizer
- [ ] Optuna integration
- [ ] Walk-forward validation
- [ ] Objective functions: Calmar, Sortino
- [ ] Weekly scheduled optimization runs

### Milestone 3.3: Scorecard
- [ ] Performance metrics calculation
  - [ ] Alpha, Beta
  - [ ] Sharpe, Sortino, Calmar ratios
  - [ ] Max drawdown, CAGR
  - [ ] Win rate, profit factor
- [ ] CHF/EUR currency conversion
- [ ] Historical comparison

---

## Phase 4: User Interface

**Goal**: Full transparency via Streamlit dashboard

### Milestone 4.1: Core Dashboard
- [ ] Account overview (equity, PnL)
- [ ] Current positions display
- [ ] Recent trades table

### Milestone 4.2: Regime & Strategy View
- [ ] Real-time regime indicator
- [ ] Active strategy display
- [ ] Parameter visibility
- [ ] Allocation breakdown

### Milestone 4.3: Analytics
- [ ] Performance charts (equity curve)
- [ ] Drawdown visualization
- [ ] Trade distribution analysis
- [ ] Optimizer results viewer

---

## Phase 5: Production Readiness

**Goal**: Reliable deployment, monitoring, alerting

### Milestone 5.1: CI/CD
- [ ] Gitea Actions pipeline
- [ ] Container builds & registry push
- [ ] Automated testing on PR
- [ ] Version tagging

### Milestone 5.2: Monitoring
- [ ] Health check endpoints
- [ ] Error alerting (email/webhook)
- [ ] Performance logging
- [ ] Resource monitoring

### Milestone 5.3: Documentation
- [x] PLAN.md (this file)
- [ ] ARCHITECTURE.md
- [ ] SECURITY.md
- [ ] RUNBOOK.md (operations)
- [ ] API reference

---

## Phase 6: Enhancements (Future)

### Email Reports
- [ ] Daily/weekly PDF reports
- [ ] Embedded charts
- [ ] Performance summary

### Additional Exchanges
- [ ] Bybit USDT perpetuals
- [ ] Alpaca crypto
- [ ] Abstract multi-exchange support

### Advanced Strategies
- [ ] Dynamic leverage based on regime
- [ ] Cross-margin mode (optional)
- [ ] Funding rate arbitrage

---

## Constraints & Decisions

| Decision | Rationale |
|----------|-----------|
| Custom engine (not Freqtrade) | Freqtrade futures requires one-way mode; we need hedge mode |
| Binance USDⓈ-M only (initial) | Best testnet support, most liquidity |
| Hedge mode ON | Long+short simultaneously for strategy isolation |
| Isolated margin | Contain risk per position |
| 4h signal timeframe | Longer swings, less noise, lower fees |
| Limit orders for entry | Better fills, avoids slippage |
| Stop-market for exits | Guaranteed execution on stop-loss |
| DuckDB for analytics | Fast OLAP queries, single file |
| Redis for state | Real-time position/order tracking |

---

## Timeline (Estimated)

| Phase | Duration | Status |
|-------|----------|--------|
| Phase 1: Foundation | 2 weeks | In Progress |
| Phase 2: Trading Logic | 3 weeks | Not Started |
| Phase 3: Optimization | 2 weeks | Not Started |
| Phase 4: UI | 1 week | Not Started |
| Phase 5: Production | 1 week | Not Started |

**Target**: Paper trading operational in ~8 weeks