# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

3-exchange spread surge detection system using Binance, OKX, and Bitget. Scans ~150 coins for inter-exchange price spread anomalies, detects surge events with per-coin adaptive baselines, and displays real-time data on a React dashboard.

## Build & Run Commands

```bash
# Build Go binary
go build -o exchange-monitor .

# Start (kills old process + builds if needed + runs)
bash start.sh

# Options: --clean (delete DB), --rebuild (force recompile)
bash start.sh --clean --rebuild

# Frontend dev (hot reload on :5173, proxies /api to :8888)
cd frontend && npm run dev

# Frontend production build
cd frontend && npm run build
```

## Architecture

### Data Flow
```
Exchange WS (Bitget + Binance + OKX) → PriceStore (in-memory)
                                          ↓
                                    scanner (Scan3Ex)
                                          ↓
                          ┌───────────────┼───────────────┐
                          ↓               ↓               ↓
                   surge_detector    momentum.go     trend.go
                   cumulative.go    trend_filter.go
                          ↓               ↓               ↓
                               dashboard (SSE hub, :8888)
                                          ↓
                               React frontend (SSE events)
```

### Main Loop (main.go)
Fixed 50ms tick: reads snap from PriceStore → Scan3Ex() → surgeDetector.Tick() → momentum.Tick() etc. Every 30s: status log. Hourly: Telegram summary.

### Package Layout

| Package | Files | Responsibility |
|---------|-------|---------------|
| `main` (root) | `main.go`, `scanner.go`, `dashboard.go`, `config.go`, `types.go`, `surge_detector.go`, `momentum.go`, `trend.go`, `cumulative.go`, `trend_filter.go` | All core logic in a single flat package |
| `exchange/` | `connector.go`, `bitget.go`, `binance.go`, `okx.go`, `helpers.go` | WS reconnector + exchange-specific REST/WS APIs |
| `db/` | `db.go`, `surge_event_repo.go` | SQLite persistence (surge_events, cm_events, trend_events, trend_signals) |
| `frontend/` | Vite + React | Real-time dashboard consuming SSE from backend |

### Key Types

- **PriceStore** — Thread-safe in-memory map of coin→exchange→price, with bid/ask spread tracking
- **ThreeExSpread** — 3-exchange scan result: coin, prices, spread %, max/min exchange
- **SurgeDetector** — Per-coin adaptive baseline surge detection with rolling window median
- **SurgeEvent** — Detected surge: coin, prices, spread, baseline, direction, leading exchange
- **MomentumTracker** — Multi-window (1s/5s/15s/60s) price change tracking per exchange
- **TrendDetector** — Cross-exchange trend state machine (idle→alert→confirmed→exhausting)
- **CumulativeTracker** — 1m/5m/1h consensus change tracking across exchanges
- **TrendFilter** — K-line based quiet detection + EMA52 trend filtering

### Exchange Connector

`PriceConnector` (exchange/connector.go) is a reusable WebSocket reconnector with exponential backoff (1s-30s), configurable ping interval, and read deadline. Bitget uses text ping frames; Binance and OKX use standard ping/pong.

### Surge Detection Logic

- **Adaptive baseline**: Per-coin rolling window (600 samples, ~30s at 50ms tick) of 3-exchange max spreads
- **Threshold**: median(spreads) × multiplier (default 3.0), with min floor (0.05%)
- **Trigger**: currentSpread > threshold AND cooldown (60s) passed
- **Direction**: Compare highest exchange deviation from median vs lowest exchange deviation
- **Leading exchange**: The exchange furthest from median price (first to reflect price move)

### Configuration Priority
`.env` vars > `config.json` > code defaults. Config struct in `config.go`.

Key env vars: `BITGET_API_KEY`, `BITGET_API_SECRET`, `BITGET_PASSPHRASE`, `BINANCE_API_KEY`, `BINANCE_API_SECRET`, `HTTPS_PROXY`, `TELEGRAM_BOT_TOKEN`, `TELEGRAM_CHAT_ID`.

### Dashboard API

| Endpoint | Description |
|----------|-------------|
| `GET /` | Serves index.html (disk first, fallback embed) |
| `GET /api/status` | Current prices snapshot |
| `GET /events` | SSE stream (prices, spread_3ex, momentum, trend, cumulative, trend_filter, surge, status) |
| `GET /api/history?coin=&exchange=` | Price history ring buffer (500 pts) |
| `GET /api/spread-history?coin=` | 3-exchange spread history |
| `GET /api/surge-events?limit=` | Surge event history from DB or memory |
| `GET /api/cm-history` | Cumulative change event history |
| `GET /api/trend-signals` | Trend filter signal history |
| `GET /api/connections` | Exchange WS health (online/stale/offline) |

### SSE Events

| Event | Data | Frequency |
|-------|------|-----------|
| `prices` | All coin prices + 3-ex spread | Every tick |
| `spread_3ex` | Top 3-ex spreads scan results | Every tick |
| `momentum` | Multi-window price change % | Every tick |
| `trend` | Trend state machine snapshots | Every tick |
| `cumulative` | Cumulative consensus changes | Every tick |
| `trend_filter` | K-line filter states | Every tick |
| `trend_signal` | Individual trend signal (enter/exit) | On event |
| `surge` | Current spread/baseline snapshots | Every tick |
| `surge_event` | New surge detection event | On detection |
| `status` | Connection health + coin count | Every tick |

### Database

SQLite at `~/Project/exchange-monitor-go/data/trades.db` (single-writer mode). Tables: `surge_events`, `cm_events`, `trend_events`, `trend_signals`.

### Coin Tracking

~150 coins in `TrackedCoins` slice (scanner.go). Each entry has Name, BN (Binance symbol), BG (Bitget symbol), OKX (OKX symbol). Active WebSocket connections: Bitget + Binance + OKX.