Skip to main content

123. Exclusive Integration with Shadow Positions

Status: Accepted Date: 2025-07-06

Context​

The Kairos module is an order management system. A critical architectural question is: what kinds of positions do these orders belong to? Should Kairos be a generic order manager capable of handling orders for both simulated positions and real, live trading positions on an exchange?

Attempting to make Kairos generic would introduce significant complexity. It would need to handle real-world concerns like exchange connectivity, API key management, partial fills, slippage, and execution fees. This would dramatically increase its scope and risk.

Decision​

The Kairos module will be designed for the exclusive purpose of managing orders for Morpheus shadow positions. It will have no knowledge of, or integration with, any live trading exchange.

This decision establishes a clear and critical architectural boundary. Morpheus is the shadow trading engine, and Kairos is its dedicated order management component. The orders it manages are themselves "shadow" orders; they exist only within our system's database.

An order is "filled" not by a response from a real exchange, but when an internal service determines that the market price (from a data feed like Bybit's) has crossed the order's price.

Consequences​

Positive:

  • Drastically Reduced Complexity: This is the most significant benefit. By not having to deal with the complexities of a real-world exchange, the Kairos module can be much simpler, more robust, and easier to build and maintain.
  • Clear Separation of Concerns: Creates a "firewall" between simulated trading and live trading. The entire Morpheus / Kairos stack is a self-contained simulation engine. A future "live trading" module would be a completely separate system, likely reusing very little of Kairos directly.
  • Safety: Massively reduces risk. A bug in Kairos can lead to incorrect simulated PnL, but it cannot possibly lose real money.
  • High-Fidelity Simulation: Allows us to focus on creating a high-fidelity simulation of order book behavior without being constrained by the APIs or limitations of a specific exchange.

Negative:

  • Not Reusable for Live Trading: The Kairos module, as designed, cannot be reused for live trading. A future live trading system would need its own, separate order management implementation that is built to handle the complexities of a real exchange.

Mitigation:

  • This is a Feature, Not a Bug: The non-reusability for live trading is a deliberate and desirable architectural choice. The requirements for simulated vs. live order management are so different that trying to combine them into a single module would be a classic design mistake. We are explicitly choosing to build the right, specialized tool for the job (simulation) rather than a generic tool that does both jobs poorly.