Ind_Aleks_ICT_Entry_V2_TS_Indie/CLAUDE.md

# CLAUDE.md

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

## Project Overview

**Ind_Aleks_ICT_Entry_V2_TS_Indie** — MQL5 chart indicator implementing ICT (Inner Circle Trading) entry methodology. Renders 10 visual plots (ZigZag, arrows, horizontal lines) directly on the price chart.

OOP architecture: main `.mq5` entry point + `CSwingDetector` class in a separate `.mqh` file.

**Encoding:** UTF-8 (no UTF-16 LE conversion needed).

## Source Files

| File | Purpose |
|------|---------|
| `Ind_Aleks_ICT_Entry_V2_TS_Indie.mq5` | Entry point: `OnInit()`, `OnCalculate()`, buffer declarations, input parameters |
| `CSwingDetector.mqh` | Core logic: `CSwingDetector` class — swing detection, BOS/MSS, all drawing (1300+ lines) |

## Build & Compile

```
validate_mql_code(mq_file_path="<full_path>\Ind_Aleks_ICT_Entry_V2_TS_Indie.mq5")
```

Or MetaEditor (F7). The `.mqproj` file is UTF-16 LE binary — do not edit directly.

**Note:** VS Code shows false errors for MQL5 built-ins (`EMPTY_VALUE`, `ArrayInitialize`, `MathMax`). Always compile with `validate_mql_code` to check real errors.

## Input Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `inp_len` | int | 5 | Liquidity Swing strength (pivot lookback) |
| `inp_len_in` | int | 10 | Structure Swing strength (pivot lookback) |
| `inp_valid_con` | enum | Close | Pullback validation: "Close" or "High/Low" |
| `inp_calc_bars` | int | 1000 | Bars to calculate (0 = all history) |

## Architecture

### CSwingDetector Class

Manages 7 of 10 drawing buffers + all 8 INDICATOR_CALCULATIONS buffers.

**Key methods:**
- `Init()` — bind external buffers, set AS_SERIES
- `Calculate()` — main per-bar loop, delegates to sub-processors
- `ProcessLiquiditySwing()` — Liquidity Swings (strength=5), ZigZag, state machine
- `ProcessStructureSwing()` — Structure Swings (strength=10), BOS/MSS detection, trend tracking
- `PivotHigh()` / `PivotLow()` — pivot detection with configurable strength

**State structures:** `SLiquiditySwingState`, `SStructureSwingState` — persisted between bars.

### 18 Buffers

**10 INDICATOR_DATA (plots):**

| # | Buffer | Plot Style | Color | Description |
|---|--------|-----------|-------|-------------|
| 0 | BufferZigZag | Line | Red | ZigZag connecting Liquidity Swings |
| 1 | BufferLiquiditySwing | Arrows | Red | Diamond dots on Liquidity Swing points |
| 2 | BufferStructureSwing | Arrows | Blue | Diamond dots on Structure Swing points |
| 3 | BufferLiquidity_Up | Histogram | Green | Liquidity levels up (RESERVED) |
| 4 | BufferLiquidity_Dn | Histogram | Green | Liquidity levels down (RESERVED) |
| 5 | BufferBOS_Up | Histogram | Blue | Break of Structure upward |
| 6 | BufferBOS_Dn | Histogram | Coral | Break of Structure downward |
| 7 | BufferMSS_Up | Histogram | Blue | Market Structure Shift upward |
| 8 | BufferMSS_Dn | Histogram | Coral | Market Structure Shift downward |
| 9 | BufferEquilibrium | Histogram | Purple | VPD/Equilibrium zones (RESERVED) |

**8 INDICATOR_CALCULATIONS (internal lookback):**

| # | Buffer | Description |
|---|--------|-------------|
| 10 | CalcSsHigh | Intermediate maximum (ss_high) for Liquidity Swings |
| 11 | CalcSsLow | Intermediate minimum (ss_low) for Liquidity Swings |
| 12 | CalcBswHigh | Bar index of intermediate maximum |
| 13 | CalcBswLow | Bar index of intermediate minimum |
| 14 | CalcSwHigh | Current Swing High value |
| 15 | CalcSwLow | Current Swing Low value |
| 16 | CalcBarSwHigh | Bar index of current Swing High |
| 17 | CalcBarSwLow | Bar index of current Swing Low |

### Buffer Initialization Pattern (Critical)

MQL5 initializes new `AS_SERIES` buffer elements to `0.0`, but `PLOT_EMPTY_VALUE = EMPTY_VALUE` (DBL_MAX). Since `0.0 != EMPTY_VALUE`, uninitialized elements draw as valid price at zero. **Fix:** set `buf[0] = EMPTY_VALUE` on every new bar for ALL INDICATOR_DATA buffers.

### INDICATOR_CALCULATIONS Lookback Pattern

Access: `calc_buf[bar + b_len]` where `b_len` = lookback distance (AS_SERIES: higher index = older bar). Always bounds-check: `lb_idx >= 0 && lb_idx < rates_total`.

## Implementation Status

### Completed
- **Liquidity Swings** — pivot detection (strength=5), ZigZag line, diamond dots, full state machine
- **Structure Swings** — pivot detection (strength=10), Valid Pullback, Valid Pivot logic
- **BOS/MSS** — Break of Structure and Market Structure Shift detection with horizontal lines
- **Current Structure Levels** — Step 12 draws unbroken levels (BOS buffers show broken levels)
- **Trend tracking** — `in_dir_big`: 1=bullish, -1=bearish

### Not Yet Implemented
- **Liquidity Levels** — `BufferLiquidity_Up/Dn` reserved but not drawn; sweep detection (`break_dem`/`break_sup`)
- **FVG** (Fair Value Gap) — 3-bar gap detection, `dfvg_*/sfvg_*` arrays
- **iFVG** (Inverted FVG) — candle close triggers inversion, `dfvg_R2_*/sfvg_R2_*` arrays
- **Equilibrium/VPD** — `BufferEquilibrium` reserved; premium/discount zones
- **Entry Signals** — `buy_signal`/`sell_signal`, `pending_buy`/`pending_sell`, all filtering

### Entry Signal Flow (target)
1. Liquidity sweep detected → 2. Trend confirmed via structure swings → 3. iFVG verified → 4. Gap between iFVG and FVG validated → 5. Filters: Equilibrium zone, FVG size, iFVG size

## Architecture Documentation (Russian)

| File | Subsystem |
|------|-----------|
| `ARCHITECTURE.md` | Main spec — system overview, parameters, signal flow, lifecycle |
| `ARCHITECTURE_FVG.md` | FVG/iFVG — gap detection, data structures, mitigation logic |
| `ARCHITECTURE_LIQUIDITY.md` | Liquidity — swing detection, level management, sweep mechanics |
| `ARCHITECTURE_SWINGS_BOS_MSS.md` | Market structure — two swing types, BOS/MSS logic, validation |
| `tz.md` | Pine Script reference (Liquidity: 414-576, Structure+BOS/MSS: 658-806, Drawing: 809-828) |

## Key Technical Constraints

- All buffers use `AS_SERIES = true` (index 0 = current bar)
- Swings: two strengths — 5 (frequent, for liquidity) and 10 (less frequent, for structure)
- iFVG inversion rule: only candle **close** triggers inversion, not wicks
- BOS/MSS buffer mapping depends on trend direction (see MEMORY.md)
- `BufferLiquidity_Up/Dn` and `BufferEquilibrium` are reserved for future modules