# ARCHITECTURE.md

## 1. Principle

Clean separation and a common forecast interface. Both sorting well-defined and
independently testable components.

```
/docs
/src
  /forecasting     common target + interface + record schema
  /baselines       naive + drift
  /arima           ARIMA component (statsmodels)
  /sax             SAX component (pure numpy)
  /hybrid          transparent evidence layer + decision states
  /data            data integrity checks
  /evaluation      forecast / distribution / economic metrics
  /validation      chronological walk-forward
  /pipeline.py     orchestration of variants -> structured records
/tests
/experiments
/results  (git-ignored)
/configs
/scripts
```

## 2. Component responsibilities

### ARIMA
- accept a closed-bar series up to the origin
- optional stationarity transform (differencing / log-return target)
- configured `(p,d,q)`; baseline config selected in `configs/`
- produce H-step forecast on the common target
- prediction interval where supported
- sequential no-lookahead out-of-sample evaluation
- refit policy (fixed vs rolling) controlled

### SAX
Preserve reference properties:
1. z-normalisation
2. PAA dimensionality reduction
3. SAX symbolic encoding
4. historical analog search
5. MINDIST-based pruning where used
6. Euclidean re-rank/validate where used
7. **strict no-lookahead**
8. forward-outcome extraction only from historical analogs whose outcome is
   known at the forecast origin (`analog_end + H <= origin`)
9. ATR-normalized outcome
10. analog count, median, P25/P75, up-rate / direction

SAX must never use the current pattern's future outcome while selecting analogs.

### Hybrid evidence layer
Not a learned-weight black box in stage one. Deterministic transparent states:
- CASE1 AGREEMENT (both bullish / both bearish)
- CASE2 DISAGREEMENT (opposite directions)
- CASE3 PARTIAL (one directional, other neutral/insufficient)
- CASE4 NO EVIDENCE (both neutral/insufficient)

Outputs `STRONG_AGREEMENT / WEAK_AGREEMENT / DISAGREEMENT / NO_EDGE / INSUFFICIENT`.

## 3. Common forecast record

Each forecast record includes at minimum:
`timestamp, symbol, timeframe, horizon H, target definition, direction,
expected return, normalized expected return, uncertainty, confidence/evidence,
model id + version, train/eval boundary, data snapshot id`.

SAX adds: `sax_word, analog_count, analog distance stats, up_rate,
forward outcome (median + q25/q75)`.

ARIMA adds: `p,d,q, fit_window, refit_policy, forecast_interval, status`.

## 4. MQL5/Python boundary (phase 1)

- Python: statistical engine (ARIMA fitting, SAX experiments, walk-forward,
  evaluation, reporting).
- MQL5: closed-bar event capture, market data source adapter (later phase).
No live trading execution in this bootstrap. The interface is a documented
`MarketDataSource` contract (see `src/data/`).