Mapa del sistema¶

Qué vas a aprender¶

Qué componentes forman FinazTradingEngine y cómo se conectan: banco de backtesting, runtime causal, motores de modelos, datos y APIs.
Qué familias de motores existen y en qué imagen corre cada una.
Cómo el banco de backtesting sirve de oráculo de paridad para el resto (paridad, shadow, ruteo).

Una plataforma, siete familias de motores¶

FinazTradingEngine es una sola plataforma. Sus motores se agrupan en familias; cada familia corre en su propia imagen con solo sus dependencias y está certificada por un gate. La ficha de cada motor está en el Catálogo de motores.

flowchart TB
    subgraph DAT["Datos y control (compartidos)"]
        PG[("PostgreSQL<br/>control, leases, outbox, publicaciones")]
        CH[("ClickHouse<br/>revision log PIT market_bars_v1")]
        RD[("Redpanda<br/>log de stream y replay")]
        MN[("MinIO / CAS<br/>snapshots sellados, artefactos")]
    end
    subgraph BT["Banco de backtesting · finaz/bench · H0–H4"]
        direction LR
        VT["VectorTA 0.2.8<br/>386 indicadores"] --> SIM["Ledger SIM-S<br/>(enteros, next-open)"]
        NT["NautilusTrader 1.231.0"] --> SIM
    end
    subgraph RT["Runtime causal · core / io · G1–G3"]
        direction LR
        CK["ClockEngine"] --> FS["FlowSpec + compiler"]
        FS --> RUN["batch · replay · stream<br/>fencing por lease PG"]
    end
    subgraph MD["Motores de modelos"]
        direction LR
        QU["quant · G4<br/>Ridge, CatBoost, ARIMA/ETS,<br/>GARCH, AutoARIMA"]
        OP["opt · G5–G6<br/>Ledoit-Wolf, VaR/ES, ERC,<br/>CP-SAT, ConstraintValidator"]
        NE["neural:s4 · G7<br/>NHITS (PyTorch)"]
        FO["chronos / timesfm25 · G8<br/>Chronos-2, TimesFM 2.5"]
    end
    subgraph AP["APIs"]
        A1["API de backtesting<br/>bench-api :8000 /v1"]
        A2["API de plataforma<br/>127.0.0.1:18300 /platform/v1"]
    end
    CH --> RT
    RD --> RT
    RT --> PG
    RT --> MN
    MN --> MD
    MD --> MN
    BT --> A1
    PG --> A2
    BT -. "oráculo: EMA golden,<br/>shadow-compare" .-> RT

Familia	Qué resuelve	Imagen	Gate
Banco de backtesting	¿Cómo habría ido una estrategia? Paridad entre dos motores	`finaz/bench:0.2.0-x86-64-v3`	H0–H4, G0-B
Runtime causal	Ejecutar el mismo flujo en batch, replay y stream con el mismo resultado	`core`, `io`	G1–G3
Tabular y estadística	Previsión con Ridge, CatBoost, ARIMA/ETS, GARCH, AutoARIMA	`quant`	G4
Riesgo, cartera y discreto	Covarianza, VaR/ES, pesos, lotes enteros y aprobación de targets	`opt`	G5, G6
Redes neuronales	Previsión con NHITS y exógenas causales	`neural:s4`	G7
Modelos fundacionales	Previsión zero-shot con Chronos-2 y TimesFM 2.5	`chronos`, `timesfm25`	G8
Datos y control	PIT, publicación transaccional, log durable, CAS	compartidos	G1, S1

El banco de backtesting por dentro¶

Capa	Dónde	Qué hace
Datos	`finazbench/data/`	Carga canónica, calendarios, limpieza `clean.v1`, remuestreo
Features	`finazbench/features/`	Registro de features, proveedores (VectorTA, Nautilus), comparador
Política	`finazbench/policy/`	P01–P20 batch y online; Q01–Q03 de cartera
Ledger	`finazbench/ledger/`	SIM-S v1 (NumPy) y v2 (Numba), sizing, informes
Adaptadores	`finazbench/adapters/`	Carriles `VTA_CPU_LEDGER`, `NT_INTENT_REPLAY`, `NT_FEATURES`, `NT_ONLINE`
Benchmarks	`finazbench/bench/`	B00–B06, walk-forward B10
API	`finazbench/api/`	`bench-api` (FastAPI) en `:8000`

Cifras de cierre (handoff.md): 386 indicadores descubiertos (375 ejecutables por la API: 33 con fórmula canónica y paridad verificada y 342 por paso directo al motor; 11 no ejecutables con motivo), 31 templates de estrategia (30 en el catálogo + Q08B; 23 implementadas: P01–P20 y Q01–Q03), paridad popular con 0 PARITY_FAIL en los carriles comparables, campaña de benchmarks de 233 casos y 2.425 muestras.

Servicios heredados

Además de bench-api, siguen vivos los dos servicios originales vectorta-service (:8001) y nautilus-service (:8002), sin perfil Compose, hasta que sus clientes migren.

El runtime causal y los motores de modelos por dentro¶

La decisión de arquitectura (docs/v2/ARQUITECTURA.md): conservar el banco de backtesting como baseline y oráculo y construir a su lado un núcleo contractual con causalidad, snapshots, publicación transaccional y recuperación. Primer vertical: snapshot → ClockEngine → EMA canónica → ResultRef, bajo la misma FlowSpec en batch, replay y stream. Sin trading en vivo.

Almacén (compartido, proyecto `finaz`)	Papel
PostgreSQL	Control y publicación (runs, flows, leases, outbox, offsets)
ClickHouse	Histórico analítico revisionado (base `finaz_te`, 141 551 barras reales)
Redpanda	Log durable reciente y simulación (stream/replay)
MinIO + volúmenes	Artefactos inmutables direccionados por contenido (CAS)

Servicio (proyecto `finaz-trading-engine`)	Perfil	Imagen
`api`	base	`finaz-te-api`
`worker-batch`	`batch`	`finaz-te-core`
`worker-stream`	`stream`	`finaz-te-core`
`replay` (job)	`replay-job`	`finaz-te-io`
`job-quant`, `job-opt`, `job-neural`, `job-chronos`, `job-timesfm25`	uno por familia	una imagen por familia

sequenceDiagram
    participant U as Cliente (Bearer)
    participant A as api :18300
    participant PG as PostgreSQL
    participant W as worker-batch
    participant S as CAS / ClickHouse
    U->>A: POST /platform/v1/flows
    U->>A: POST /platform/v1/runs (Idempotency-Key)
    A->>PG: run QUEUED + outbox
    W->>PG: reclama (lease + fence)
    W->>S: calcula y escribe artefacto
    W->>PG: publica (commit) → SUCCEEDED
    U->>A: GET /platform/v1/results/{ref}
    A-->>U: 200 + ResultRef

Los motores de modelos corren como jobs one-shot (uno por familia) que leen sus entradas del CAS y escriben su artefacto con sha256. El detalle está en la Parte VII y en Modelos G4–G8.

Cómo se valida todo contra el oráculo¶

Oráculo: el EMA golden [1..6] → [null, null, 2, 3, 4, 5] está congelado y el runtime debe reproducirlo bit a bit.
Shadow-compare: el runtime calcula lo mismo que el banco sin publicar y se exige match == true con igualdad exacta.
Ruteo por flujo: cada flujo se sirve desde el banco, en modo sombra o desde el runtime (valores legacy, shadow, v2 en la configuración); el cambio es un dato auditado y reversible (ver Backup y rollback).

Dónde corre cada cosa¶

Qué	Dónde
Banco de backtesting	Contenedores `finaz/bench` (perfiles `dev`, `bench-api`, `bench`), portátil o servidor
Runtime, API de plataforma y motores de modelos	Servidor `finaz-new` (24 CPU, 251 GiB, sin GPU), usuario `iort-user`
Datos compartidos	Proyecto Compose `finaz` del servidor (no se toca)
Este manual	MkDocs Material → Cloudflare Pages (`finaztradingengine.iort.io`)

Resumen¶

Una plataforma con siete familias de motores; el banco de backtesting es el oráculo de paridad.
Cada familia corre en su imagen y la certifica un gate; todo en PASS salvo S5.
La plataforma reutiliza PG/CH/Redpanda/MinIO del proyecto finaz; nunca los duplica.
Oráculo + shadow + ruteo reversible permiten migrar flujo a flujo sin escritores duales.

Para practicar¶

Dibuja de memoria el camino de un POST /platform/v1/runs hasta el GET /results.
¿Por qué el runtime no levanta su propio PostgreSQL?
¿Qué tendría que pasar para mover un flujo de shadow a v2?
Sitúa en el diagrama de familias dónde corre CP-SAT y qué componente aprueba su salida.