Warrior_EA/SIGNALS.md

# Signals Subsystem Documentation

## Overview
The signals subsystem provides a modular framework for generating, filtering, and combining trading signals in the Warrior_EA expert advisor. It supports both traditional indicator-based signals and advanced AI/ML-driven signals, as well as session and news filters for robust, context-aware decision-making.

## Architecture
- **Signal Classes:**
  - Each indicator or logic type is encapsulated in its own class (e.g., `CSignalMA`, `CSignalLSTM`, `CSignalNewsFilter`, `CSignalSessionFilter`).
  - All signal classes derive from a common base (e.g., `CExpertSignalCustom` or `CExpertSignalAIBase`).
- **Signal Registry:**
  - `Signals.mqh` acts as a registry, including and exposing all available signal/filter modules for use in the EA.
- **Filter Signals:**
  - Session and news filters are implemented as signals, allowing flexible composition and enabling/disablement.
- **AI/ML Integration:**
  - AI-based signals (e.g., LSTM) inherit from a specialized base and are designed for integration with the neural network subsystem.

## Key Classes & Responsibilities
- **CSignalMA**
  - Generates signals based on the Moving Average indicator.
  - Supports parameterization (period, shift, method, applied price) and multiple pattern weights.
- **CSignalMACD**
  - Generates signals from the MACD oscillator: line direction, line reversal, main/signal crossing, zero-level crossing, and single/double price-oscillator divergence (6 patterns).
  - Ported from the MQL5 standard library; the only classic signal carrying a divergence model.
- **CSignalIchimoku**
  - Full Ichimoku Kinko Hyo repertoire in 12 patterns, numbered weakest to strongest so the last match in the chain is the highest-conviction one.
  - **Confirming states, all weight 10** (the same floor `CSignalMA`/`CSignalRSI`/`CSignalMACD` give their `Pattern_0` — each holds across long stretches of bars, so none may approach the open gate alone): price vs the cloud (0), projected cloud colour (1), Chikou Span clear of both past price and the cloud plotted there (2). The **weak** TK cross grade (3) sits at the same floor — doctrine's "stand down" case.
  - **Events, 30–100**: Kumo twist (4, 30); **neutral** TK cross inside the cloud (5, 40); Kijun-sen cross (6, 60); Kijun-sen bounce off a base line holding its level (7, 70); Kumo breakout (8, 80); breakout through a thin cloud (9, 90); **strong** TK cross clear of the cloud (10, 90); Sanyaku Kōten/Gyakuten three-roles alignment (11, 100).
  - Written from scratch — there is no Ichimoku module in the MQL5 standard library.
  - MT5's `iIchimoku` shifts only the *drawing*, not the buffers, so the cloud under bar `i` is `SenkouSpan*(i + Kijun)` and the Chikou plotted at bar `i` would be a future close. The class applies the offset and never reads `ChinkouSpan()`; see its class comment.
- **CSignalLSTM**
  - Generates signals using an LSTM-based AI model.
  - Supports pattern weighting and integrates with the neural network subsystem for stateful, sequence-based predictions.
- **CSignalNewsFilter**
  - Filters signals based on economic news events and impact levels.
  - Configurable lookback window and impact threshold.
- **CSignalSessionFilter**
  - Filters signals based on trading session (London, New York, Tokyo).
  - Configurable session enablement and time intervals.

## Features
- **Modularity:** Each signal/filter is a self-contained class, easily enabled/disabled or extended.
- **Extensibility:** New signals (traditional or AI-based) can be added with minimal changes to the registry.
- **Configurable:** All major parameters (indicator settings, session times, news impact, etc.) are exposed for runtime configuration.
- **AI/ML Ready:** Designed to support both classic and neural network-based signals, with clear integration points.

## Integration Points
- **Signal Generation:** All trading logic (entry/exit) is driven by the combined output of enabled signals and filters.
- **AI/ML:** LSTM and other AI signals can be prioritized or blended with traditional signals for hybrid strategies.
- **Session/News Filtering:** Non-signal filters (session, news) are preserved and improved for robust, context-aware trading.

## Design Notes
- **Separation of Concerns:** Each signal/filter class has a single responsibility, improving clarity and testability.
- **Dynamic Configuration:** Move toward runtime-configurable signal pipelines for maximum flexibility.
- **Backward Compatibility:** Traditional signals are preserved but can be phased out in favor of AI/ML-driven logic.

## Recommendations
- **Unit Testing:** Add tests for each signal/filter class, especially for edge cases and parameter validation.
- **Refactor for Dynamic Pipelines:** Move from hard-coded signal inclusion to a dynamic, user-configurable pipeline.
- **Documentation:** Maintain this file and add inline comments for all new signals and filters.

---
This documentation covers the Signals subsystem. Repeat this process for all other modules to ensure full codebase coverage and maintainability.