# CLAUDE.md

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

## Project Overview

This is a Python-based algorithmic trading system for financial markets that implements technical indicator analysis, signal generation, decision making, and risk management. It integrates with Tinkoff Invest API for market data and trading.

## Development Setup

### Environment Setup
- Python 3.9-3.12 (managed via Poetry)
- Install dependencies: `poetry install`
- Activate virtual environment: `poetry shell`
- Environment variables are in `.env` (contains Tinkoff API tokens)

### Docker Development
- Build image: `docker build -f dockerfiles/Dockerfile -t market-trade .`
- Main Dockerfile uses Poetry 1.7.1 and Python 3.11
- Requires SSH mount for private tinkoff-grpc dependency

### Running Tests
- Test files located in `market_trade/tests/`
- Run test: `python market_trade/tests/test_decision.py`
- Run specific test: `python market_trade/tests/test_dataloader.py`

### Data Tools
Scripts in `tools/` directory for data collection:
- `save_currencies_data.py` - Collect currency market data
- `save_shares_data.py` - Collect stock market data
- `get_shares_stats.py` - Generate trading statistics
- Usage: `python tools/<script_name>.py [options]`

## Architecture

### Core Trading Pipeline (docs/trading-flow.md)

The system follows this data flow:
1. **SELECT INSTRUMENT** - Choose trading instrument
2. **GET_CANDLES(10000)** - Fetch historical candlestick data
3. **RETRO TRAINING** - Backtest signals on historical data
4. **STREAM PROCESSING**:
   - Receive real-time market messages
   - Accumulate data in sliding window
   - Update window with each new message
   - Generate trading signals

### Module Structure

#### `market_trade/core/` - Core Trading Logic

**Signal Processing Chain:**
1. **Indicators** (`indicators.py`, `indicators_v2.py`) - Technical indicator calculation
   - Base class: `coreIndicator`
   - Bollinger Bands: `ind_BB`
   - All indicator classes (Ind_*.py): ADX, Alligator, DonchianChannel, Envelopes, Gator, Ishimoku, LRI, STD, Stochastic, bollingerBands

2. **Signals** (`signals.py`, `signals_v2.py`) - Signal generation from indicators
   - Base class: `coreSignalTrande` with three modes:
     - `online` - Real-time signal generation
     - `retro` - Expanding window backtesting
     - `retroFast` - Sliding window backtesting
   - Signal implementations: `signal_BB` (Bollinger Bands signal)
   - Aggregator: `signalAgrigator` manages multiple signal instances

3. **Decision Manager** (`decisionManager.py`, `decisionManager_v2.py`) - Trading decisions
   - Class: `decsionManager`
   - Combines signals from `signalAgrigator`
   - Uses `trandeVoter` for probability matrix generation
   - Methods:
     - `getSignalTest()` - Test signal generation
     - `generateMatrixProbability()` - Create probability matrices from backtest
     - `getOnlineAns()` - Real-time decision making

4. **Trade Voter** (`trandeVoter.py`) - Probability-based decision weighting
   - Generates probability matrices from historical signal performance
   - Weights multiple signals to produce final decision

5. **Risk Manager** (`riskManager.py`) - Position sizing and risk controls
   - Class: `riskManager`
   - Combines signal decisions with risk parameters

6. **Deal Manager** (`dealManager.py`) - Trade execution and management
   - Class: `DealManager`
   - Manages active positions and orders

**Helper Modules:**
- `CoreTradeMath.py` - Mathematical operations for indicators (moving averages, STD)
- `CoreDraw.py` - Visualization utilities for indicators and signals

#### `market_trade/data/` - Data Loading

- `dataloader.py` - Contains `DukaMTInterface` class
  - Converts Dukascopy format candlestick data to internal format
  - Separates bid/ask candlesticks from multi-indexed CSV
  - Handles both file paths and DataFrames

#### `market_trade/tests/` - Testing

- Test files demonstrate usage patterns:
  - `test_decision.py` - Shows complete decision manager workflow with retro training
  - `test_dataloader.py` - Data loading tests

### External Dependencies

- **tinkoff-grpc** - Private GitHub repo for Tinkoff Invest API integration
  - Located at: `git@github.com:strategy155/tinkoff_grpc.git`
  - Used in tools for market data collection
- **Data Analysis**: pandas, numpy, scipy, matplotlib, plotly, mplfinance
- **Web Scraping**: requests-html, beautifulsoup4, selenium
- **Development**: JupyterLab (notebooks in `notebooks/`)

## Key Constants (market_trade/constants.py)

- `ROOT_PATH` - Project root directory
- `CANDLESTICK_DATASETS_PATH` - Path to candlestick data: `data/candlesticks/`
- `TEST_CANDLESTICKS_PATH` - Test dataset: `data/EURUSD_price_candlestick.csv`
- `TINKOFF_TOKEN_STRING` - Production API token (from .env)
- `SANDBOX_TOKEN_STRING` - Sandbox API token (from .env)
- `TINKOFF_API_ADDRESS` - API endpoint: 'invest-public-api.tinkoff.ru:443'

## Data Formats

### Candlestick Data
Expected DataFrame columns:
- `date` - Timestamp
- `open`, `high`, `low`, `close` - OHLC price data
- For bid/ask data: Multi-indexed with ('bid'/'ask', 'open'/'high'/'low'/'close')

### Signal Configuration Dictionary
```python
{
    'signal_name': {
        'className': signal_class,  # e.g., sig_BB
        'indParams': {...},          # Indicator parameters
        'signalParams': {            # Signal parameters
            'source': 'close',       # Source price column
            'target': 'close'        # Target price column for analysis
        },
        'batchSize': 30              # Window size
    }
}
```

## Development Notes

- Code contains Russian comments and variable names (e.g., "агрегатор", "индикаторы")
- Version 2 modules (`*_v2.py`) represent newer implementations
- The system uses sliding window approach for real-time signal generation
- Backtesting generates probability matrices that weight signal reliability
- Data symlink: `data/` -> `/var/data0/markettrade_data`