# CENTAUR QUANT ARCHITECTURE — FOUNDATIONAL CHARTER
Version: 1.0.0 | Status: RATIFIED | Owner: Senior Quant Data Engineer / Lead MQL5 Architect

This document is the single source of truth for all module development within this workspace.
Every file, class, schema, and payload MUST conform to the constraints below. Deviations require a charter amendment.

---

## 1. PROJECT BACKGROUND & PHILOSOPHY

The **Centaur System** is a hybrid quantitative architecture with three cooperating agents:

| Agent | Layer | Role |
|-------|-------|------|
| **The Executor** | MQL5 Expert Advisor | Deterministic logic: Smart Money Concepts (SMC), market structure, entry/exit rules. |
| **The Probability Analyst** | LLM (Python backend) | Contextual probability scoring of each setup. Advisory only — NEVER blocks execution. |
| **The Data Harvest Core** | Python + Relational DB | Ingests every tick, historical context, AI score, and trade outcome. Feeds iterative learning / ML. |

Non-Negotiable Principles:
1. **Data Harvest is the true core.** Every tick, every historical context, every AI probability score, every trade outcome MUST be recorded.
2. **Instrument-Agnostic.** Fully dynamic across multi-currency, commodities, indices, crypto. No per-instrument hardcoding.
3. **Strict Separation.** Execution environment (MT5) is isolated from analytical (Python) and storage (DB) backends. They communicate ONLY via the Universal Communication Bridge.

---

## 2. CORE OBJECTIVES

1. **Multi-Asset Execution Engine (MQL5)** — Dynamic, symbol-agnostic EA. Automatically adapts to any instrument's tick size, point value, and contract specifications via SymbolInfoDouble()/SymbolInfoInteger() + ATR-based normalization.
2. **Historical & Real-Time Data Integration** — Analyze the live tick AND package higher-timeframe structural context into the payload before requesting AI analysis.
3. **Standardized Data Protocol (SDP)** — Strict, unified JSON protocol for ALL data flowing out of MT5 (prices, indicators, account state) and into MT5 (AI scores, execution commands).
4. **Telemetry & Database Architecture** — Python backend routes MQL5 telemetry, AI predictions, and final trade outcomes (Win/Loss, R-Multiple) into a structured relational database (PostgreSQL production / SQLite fallback) for ML and post-trade analysis.
5. **Anti-Veto Trade Management** — The EA executes on its deterministic edge. The AI probability score dictates ONLY position sizing and dynamic trade management. It NEVER blocks the baseline algorithmic execution.

---

## 3. METHODOLOGY & PROTOCOL

### 3.1 Universal Communication Bridge
- Transport: Asynchronous TCP/IP socket (primary) or ZeroMQ (ZMQ) (alternative/upgrade path). Single transport abstraction layer in MQL5 and Python.
- MT5 = data publisher / client. Python backend = central router & API gateway.
- MQL5 side MUST be non-blocking: OnTimer-driven sends, socket reads polled, never blocking tick processing.

### 3.2 The SDP Schema (Standardized Data Protocol)
Every outbound payload from MQL5 MUST adhere to this schema (JSON):

```json
{
  "SDP_Version": "1.0",
  "Timestamp": "2026-08-12T09:20:00.000Z",
  "Symbol": "XAUUSD",
  "Timeframe": "M15",
  "Action_Type": "Setup_Detected | Trade_Opened | Trade_Closed | Tick_Harvest | Heartbeat",
  "Historical_Context": [ { "swing_high": 1.2345, "swing_low": 1.2300, "time": "..." } ],
  "Algorithmic_Confidence_Score": 0.0,
  "Payload": { }
}
```

Mandatory keys for ALL actions: `SDP_Version`, `Timestamp`, `Symbol`, `Timeframe`, `Action_Type`.
`Historical_Context` (array of recent swings) and `Algorithmic_Confidence_Score` MUST be populated for `Setup_Detected` / `Trade_*` actions.
Inbound payloads (Python → MT5) carry AI scores + sizing directives under a reserved `AI_Advisory` envelope.

### 3.3 Continuous Feedback Loop
- Every trade closure triggers a `Trade_Closed` payload linking the final financial outcome (Profit/Loss, R-Multiple) to the original AI probability score.
- This tuple (score → outcome) is the training signal for future weighting adjustments in the DB.
- Correlation and calibration analytics run on the Python side; results may feed back as advisory metadata — never as vetoes.

---

## 4. TECHNICAL STANDARDS & CONSTRAINTS

1. **Dynamic Normalization — STRICTLY FORBIDDEN: hardcoded point buffers** (e.g., "5 points for Gold").
   - ALL buffers, stop-losses, take-profits, and ATR offsets derived from `iATR()` and dynamic `SymbolInfoDouble()` calculations.
   - Distance = f(ATR_period, ATR_multiplier, point, tick_size, trade_tick_value, margin/contract specs) — resolved at runtime per symbol.
2. **Non-Blocking Architecture** — MQL5 must remain ultra-lightweight. Socket I/O async (OnTimer / non-blocking reads). MT5 NEVER waits or freezes for Python or the DB.
3. **Modular OOP Design** — Strict MQL5 `#property strict`, full OOP. Isolated classes per concern:
   - `Core/` — symbol normalization, account state, runtime config
   - `Data/` — market data harvest, historical context packaging
   - `Execution/` — order management, dynamic trade management, anti-veto sizing
   - `Network/` — transport abstraction, non-blocking socket client, serialization

---

## 5. DIRECTORY LAYOUT (CANONICAL)

```
Centaur_Quant_Architecture/
├── 00_CONCEPT/          # Charter + design documents (this file)
├── MQL5/
│   ├── Include/
│   │   ├── Core/        # SymbolNormalizer, AccountState, Config
│   │   ├── Data/        # DataHarvester, ContextPackager
│   │   ├── Execution/   # OrderExecutor, TradeManager, SizingEngine
│   │   └── Network/     # Transport (TCP/ZMQ), SDP Serializer
│   └── Experts/         # CentaurExecutor.mq5 (thin composition root)
├── Python/
│   ├── router/          # Central router / API gateway (ZMQ/TCP server)
│   ├── database/        # ORM, migrations, telemetry ingestion
│   └── models/          # Probability Analyst, ML calibration
└── Database/            # Schema DDL, migrations, seed data
```

---

## 6. DEFINITION OF DONE (PER MODULE)

- Conforms to SDP schema v1.0 (validated by schema test).
- Zero hardcoded per-symbol point values; all distances normalized at runtime.
- Non-blocking: no MT5 freeze risk under socket failure/timeout.
- Telemetry event emitted for every lifecycle action (setup, open, close, error).
- Compiles clean with `#property strict`; no warnings.