Engines

⚠️ This page may change as the Engine architecture is still being designed.

Engines are the processing components in TheoryCraft that consume events and perform specific tasks. Each Engine receives MarketEvents and/or BrokerEvents, then executes its designated function.

Design Principle

One Engine = one event consumer with a single, stable responsibility.

Each Engine:

  • Consumes MarketEvent and/or BrokerEvent streams
  • Can emit orders, metrics, or artifacts
  • Does exactly one thing
  • Can be plugged or unplugged without breaking the system

If two responsibilities have different rhythms, time horizons, or outputs, they belong in separate Engines. This separation ensures clean boundaries, testability, and flexibility.

Types of Engines

StrategyEngine

Transforms market events into trading decisions. The StrategyEngine is the decision-making brain: it evaluates strategy logic and produces signals.

Responsibilities:

  • Evaluate entry and exit conditions
  • Produce signals (entry, exit, sizing)
  • Remain stateless or minimally stateful

Inputs: MarketEvent, optionally BrokerEvent (for position awareness)

Outputs: Order intentions (not direct execution)

The StrategyEngine focuses purely on decision logic. It doesn't execute orders, calculate statistics, or manage risk. Those responsibilities belong to other Engines.

PortfolioEngine

Coordinates multiple strategies. The PortfolioEngine handles capital allocation, aggregate risk, and strategy arbitration.

Responsibilities:

  • Allocate capital across strategies
  • Manage global risk exposure
  • Arbitrate between competing signals
  • Control correlation and exposure

Inputs: Signals from multiple StrategyEngines, Broker state

Outputs: Aggregated orders

Why separate from StrategyEngine? Strategy logic and portfolio management operate at different levels. A StrategyEngine knows nothing about other strategies. It just produces signals. The PortfolioEngine sees the full picture and decides how to combine them.

Without a PortfolioEngine, you're limited to single-strategy trading.

RiskEngine

Controls risk before execution. The RiskEngine validates order intentions against risk rules before they reach the Broker.

Responsibilities:

  • Enforce drawdown limits
  • Monitor maximum exposure
  • Control leverage
  • Implement kill-switch logic
  • Apply risk management rules

Inputs: Order intentions, Broker state

Outputs: Validated or blocked orders

Why separate? Separating risk control from strategy logic is an institutional best practice. It creates a clear boundary: strategies propose, risk controls dispose.

StatisticsEngine

Measures performance after the fact. The StatisticsEngine tracks trades and computes metrics to evaluate strategy performance.

Responsibilities:

  • Calculate metrics: PnL, drawdown, Sharpe ratio, Sortino ratio, expectancy
  • Aggregate by trade, day, or period
  • Generate performance reports and time series

Inputs: BrokerEvent, optionally MarketEvent

Outputs: Metrics, reports, time series data

Why separate from StrategyEngine? Statistics operate at different frequencies and use non-causal logic (they look at completed trades). Mixing statistics into strategy code risks look-ahead contamination. Keeping them separate ensures clean backtesting.

OptimizerEngine

Explores parameter space. The OptimizerEngine runs multiple backtests with different configurations to find optimal parameters.

Responsibilities:

  • Define parameter search space
  • Launch N backtests
  • Collect and compare metrics
  • Return optimal configurations

Inputs: Parameter ranges, strategy definitions

Outputs: Ranked configurations, optimization reports

The OptimizerEngine is a "meta" engine. It orchestrates other engines and pipelines rather than processing market data directly, and operates outside real-time.

LiveGuardEngine

Monitors live execution. The LiveGuardEngine watches for anomalies and divergences during live trading.

Responsibilities:

  • Detect backtest vs live divergence
  • Monitor abnormal latency
  • Flag Broker/Market inconsistencies
  • Trigger alerts

Inputs: MarketEvent, BrokerEvent, system metrics

Outputs: Alerts, diagnostics

The LiveGuardEngine is only relevant in live trading, but provides professional-grade monitoring for production systems.

How Engines Work

A typical workflow:

  1. MarketSource emits MarketEvents (price data, indicators)
  2. Broker emits BrokerEvents (order updates, position changes)
  3. Engine receives one or both event streams
  4. Engine processes events and performs its task
  5. Engine emits outputs (orders, metrics, alerts)

This event-driven design ensures the same Engine logic works across backtesting, paper trading, and live trading.

Composing Engines

While each workflow connects to a single primary Engine, Engines can be composed:

  • StrategyEngine → RiskEngine → Broker
  • Multiple StrategyEngines → PortfolioEngine → RiskEngine → Broker
  • Any configuration → StatisticsEngine (observing)

This composability lets you build sophisticated trading systems from simple, focused components.

Next Steps