Chan/CLAUDE.md

CLAUDE.md

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

Project Overview

缠论 (Chan Theory) technical analysis system for Freqtrade. Implements Chan Zhong Shui Chan's theory for crypto/stock trading, including fractal (分型), stroke (笔), segment (线段), pivot/center (中枢), and buy/sell point (买卖点) detection.

Governance

• ESS 文档：docs/PROJECT_PROFILE.md、docs/ECR/、docs/ENGINEERING_SPEC/
• 正式引擎包：chanlun/；strategies / web 已用 from chanlun import ...
• 根目录 Chan*.py / TF_DF.py 仍为 兼容 shim（旧脚本可用）

Core Architecture

Chan Theory Engine (chanlun/)

chanlun/
  core/          # KLU KLC BI SBI SEG ZS BIZS BSP Enum CTime
  pipeline/      # orchestrator(ChanLun) + timeframe(TF_DF) + builders/
  indicators/    # ChanMACD*
  analysis/      # Zone Classifier Pivot Heng PY Find_Trend ...

Data processing pipeline (each step feeds the next):

1. chanlun.core.ChanKLU — Raw K-line unit with TA indicators and pattern recognition
2. chanlun.core.ChanKLC — Combined K-line: inclusion + fractal; .next/.pre linked list
3. chanlun.core.ChanBI — Stroke (笔)
4. chanlun.core.ChanSBI — Special stroke → SEG
5. chanlun.core.ChanSEG — Segment (线段)
6. chanlun.core.ChanZS / ChanBIZS — Centers (中枢)
7. chanlun.core.ChanBSP — Buy/Sell points
8. chanlun.pipeline.orchestrator.ChanLun — Orchestrator
9. chanlun.pipeline.timeframe.TF_DF — Timeframe facade；实现拆在 pipeline/builders/

Services

• 外部 DATA_SERVICE — 行情服务（env: DATA_SERVICE_URL）；本仓库可不含 data_provider 源码
• web/ — Flask UI：create_app() + api/ blueprints + services/；前端 static/js/app/。默认端口见 web/config.py（FLASK_PORT，常见 8128）
• strategies/ — Freqtrade strategies（本 ECR 不改）
• config/ — Freqtrade configs（本 ECR 不改）

Data Flow

Exchange / DATA_SERVICE → Freqtrade Strategy / web → ChanLun → TF_DF
  → KLU → KLC → BI → SBI → SEG → ZS → BSP

Common Commands

Freqtrade Trading

# Live trade
freqtrade trade -c ./user_data/Chan/config/<config>.json --strategy <StrategyName> --strategy-path ./user_data/Chan/strategies

# Backtest
freqtrade backtesting -c ./user_data/Chan/config/<config>.json --strategy <StrategyName> --strategy-path ./user_data/Chan/strategies --timerange=20251008-

# Download data
freqtrade download-data -c ./user_data/Chan/config/<config>.json -t 1m 1h 1d --pairs BTC/USDT:USDT --timerange=20240101-

# Hyperopt
freqtrade hyperopt --hyperopt-loss SharpeHyperOptLossDaily --spaces roi --strategy <StrategyName> --strategy-path ./user_data/Chan/strategies -c ./user_data/Chan/config/<config>.json -e 200 --timerange=20250201-20250901

# Plot
freqtrade plot-dataframe --strategy <StrategyName> --datadir user_data/data/binance -c ./user_data/Chan/config/<config>.json --timerange=20250721-

Data Provider

# Docker
cd data_provider && docker compose up -d

# Direct
cd data_provider && python main.py

# With custom config
CONFIG_PATH=./config.json python main.py

Web UI

cd web && python app.py
# or via gunicorn:
gunicorn -w 4 -b 0.0.0.0:8123 app:app

# Deploy scripts:
cd web && ./deploy.sh          # standard
cd web && ./deploy_venv.sh     # Ubuntu 22.04+ (venv)

Docker (Freqtrade)

sudo docker compose run --rm chanlun_btc backtesting -c ./user_data/Chan/config/<config>.json --strategy <StrategyName> --strategy-path ./user_data/Chan/strategies --timerange=20250721-

Key Conventions

• All Chan theory classes are prefixed with Chan (e.g., ChanBI, ChanZS)
• Strategies import ChanLun and add sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))) to import from parent
• MACD params: MACD(26, 52, 9) by default (slow period 52 instead of standard 26)
• Enums in ChanEnum.py use auto() values
• ChanKLC is a linked-list style data structure with .next/.pre pointers
• The TF_DF class is the primary data container per timeframe
• K-line direction uses Chan_KLINE_DIR (UP/DOWN/COMBINE/INCLUDED)
• All text comments/commits are in Chinese