btc-trading/AGENTS.md

# AGENTS.md - AI Coding Assistant Guidelines

## Project Overview
BTC Accumulation Bot - Data Collection & Backtesting Phase. High-performance system for
cbBTC on Hyperliquid with TimescaleDB. Core components: Data Collector (WS),
Indicator Engine (SMA, etc.), Brain (Decision Logic), and Backtester.

## Build/Run Commands

### Docker (Primary deployment - Synology DS218+)
```bash
cd docker && docker-compose up -d --build   # Build and start all services
docker-compose logs -f data_collector       # View logs
bash scripts/deploy.sh                      # Full deploy
```

### Development
```bash
cd src/api && uvicorn server:app --reload --host 0.0.0.0 --port 8000
# Docs: http://localhost:8000/docs | Dashboard: http://localhost:8000/dashboard
cd src/data_collector && python -m data_collector.main
```

### Testing
```bash
pytest                                                                       # All tests
pytest tests/data_collector/test_websocket_client.py                         # Single file
pytest --cov=src --cov-report=html                                           # With coverage
```

## Project Structure
```
src/
├── data_collector/              # WebSocket client, buffer, database
│   ├── __init__.py              # Package exports (all public classes)
│   ├── main.py                  # Entry point, orchestration
│   ├── websocket_client.py      # Hyperliquid WS client
│   ├── candle_buffer.py         # Circular buffer with async flush
│   ├── database.py              # asyncpg/TimescaleDB interface
│   ├── backfill.py              # Historical data backfill
│   ├── custom_timeframe_generator.py  # 37m, 148m, 1d aggregation
│   ├── indicator_engine.py      # SMA/EMA computation & storage
│   ├── brain.py                 # Strategy evaluation & decision logging
│   └── backtester.py            # Historical replay driver (server-side)
├── api/
│   ├── server.py                # FastAPI app, endpoints for data/backtests
│   └── dashboard/static/index.html  # Real-time web dashboard with client-side simulation
└── strategies/
    ├── base.py                  # Base strategy interface
    └── ma_strategy.py           # Configurable MA strategy (period: 5-500)
config/data_config.yaml          # Operational config & indicator settings
docker/                          # Docker orchestration & init-scripts
scripts/                         # Deploy, backup, & utility scripts
```

## Architecture & Data Flow

### Live Trading (Server-Side)
```
Live: WS -> Buffer -> DB -> CustomTF -> IndicatorEngine -> Brain -> Decisions
                                              │             │
Backtest: DB (History) -> Backtester ─────────┴─────────────┘
```

### Client-Side Simulation (Dashboard)
```
User Input -> API /candles/bulk -> Browser (ClientStrategyEngine) -> Chart Visualization
                    ↓                                              ↓
            Historical Data                                Buy/Sell Markers
```

- **Stateless Logic**: `IndicatorEngine` and `Brain` are driver-agnostic. They read from DB
  and write to DB, unaware if the trigger is live WS or backtest replay.
- **Consistency**: Indicators are computed exactly the same way for live and backtest.
- **Visualization**: Dashboard queries `indicators` and `decisions` tables directly.
  Decisions contain a JSON snapshot of indicators at the moment of decision.
- **Client-Side Simulation**: All strategy simulations run in the browser using `ClientStrategyEngine`.
  The server only provides historical candle data via API. This minimizes server load and allows
  interactive backtesting with configurable parameters (MA period 5-500).
- **Full Historical Display**: After simulation, the chart displays the complete date range used,
  not just the default 1000 recent candles.

## Key Dataclasses

```python
@dataclass
class Candle:                    # Standard OHLCV
    time: datetime; symbol: str; interval: str; ...

@dataclass
class Decision:                  # Brain output
    time: datetime; symbol: str; decision_type: str; confidence: float
    indicator_snapshot: Dict;    # Values seen by Brain at decision time
    backtest_id: Optional[str]   # UUID if backtest, None if live
```

## Database Schema (TimescaleDB)

| Table | Purpose | Key Columns |
|-------|---------|-------------|
| `candles` | OHLCV data | `(time, symbol, interval)` UNIQUE |
| `indicators` | Computed values | `(time, symbol, interval, indicator_name)` UNIQUE |
| `decisions` | Buy/sell signals | `(time, symbol, interval, backtest_id)` |
| `backtest_runs` | Run metadata | `(id, strategy, config, results)` |

- `decisions` table stores `indicator_snapshot` JSONB for exact replay/audit.
- Compression enabled on all hypertables (7-day policy).

## API Endpoints (src/api/server.py)

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/candles` | Query raw candles |
| GET | `/api/v1/indicators` | Query computed indicators (MA, RSI, etc.) |
| GET | `/api/v1/decisions` | Query signals (live or backtest) |
| GET | `/api/v1/backtests` | List historical backtest runs |
| POST | `/api/v1/backtests` | Trigger a new backtest (async background task) |
| GET | `/api/v1/stats` | 24h trading stats |

## Code Style Guidelines

- **Imports**: Stdlib, then Third-party, then Local (relative within package).
- **Async**: Use `async/await` for all I/O. Use `asyncpg` pool.
- **Typing**: strict type hints required. `Optional[T]`, `List[T]`.
- **Logging**: Use `logger = logging.getLogger(__name__)`.
- **Config**: Load from `config/data_config.yaml` or env vars.

## Strategy Configuration

The system uses a single configurable Moving Average strategy (`ma_strategy`) with a dynamic period (5-500).

### Strategy Files
- `src/strategies/base.py` - Base strategy interface with `SignalType` enum
- `src/strategies/ma_strategy.py` - Configurable MA strategy implementation

### Client-Side vs Server-Side

| Feature | Client-Side (Dashboard) | Server-Side (CLI/API) |
|---------|------------------------|----------------------|
| **Purpose** | Interactive simulation | Production backtesting |
| **Strategy** | Single configurable MA (period 5-500) | Configurable via strategy registry |
| **Indicators** | Calculated in browser (SMA, RSI, etc.) | Pre-computed in database |
| **Data Flow** | API → Browser → Chart | DB → Backtester → DB |
| **Performance** | Fast, interactive | Thorough, historical |

### Simulation Workflow
1. User selects date range and MA period (5-500) in dashboard sidebar
2. Browser fetches full historical data from `/api/v1/candles/bulk`
3. `ClientStrategyEngine` calculates indicators client-side using JavaScript
4. Simulation runs on complete dataset, generating buy/sell signals
5. Chart updates to show full historical range with trade markers
6. Results displayed in sidebar (win rate, P&L, profit factor)

## Common Tasks

### Add New Indicator
1. Add to `config/data_config.yaml` under `indicators`.
2. Update `IndicatorEngine._compute_indicator` in `src/data_collector/indicator_engine.py` if new type (non-SMA).
3. No DB schema change needed (rows are generic).

### Run Backtest
```bash
# CLI
python -m data_collector.backtester --symbol BTC --intervals 37m --start 2025-01-01

# API
curl -X POST http://localhost:8000/api/v1/backtests \
  -H "Content-Type: application/json" \
  -d '{"symbol": "BTC", "intervals": ["37m"], "start_date": "2025-01-01"}'
```