Skip to main content

61. Demo Instance as Live Mirror

Status: Accepted Date: 2025-07-06

Context​

As part of our three-tier architecture (adr://instance-purpose-clarity), the R (Demo/Reader) instance serves as the final validation gate before a strategy is deployed live. To be a valid gate, it must accurately predict how the strategy will behave in the live environment. If the demo environment's logic, configuration, or risk rules differ from live, the validation is meaningless and provides a false sense of security.

Decision​

The R instance must be an exact mirror of the W (Live) instance in every respect except for the credentials it uses. Specifically:

  1. Shared Configuration: The R instance will load the exact same version-controlled configuration files for strategies, risk parameters, and application logic as the W instance.
  2. Identical Logic: The code running on both instances must be from the same commit/build.
  3. Testnet API: The only difference is that the R instance will be configured, via environment variables, to use the exchange's testnet/demo API endpoints and credentials.

The purpose of the R instance is not to "test new features" but to validate the behavior of the production-ready code in a realistic, but financially risk-free, environment.

Consequences​

Positive:

  • High-Fidelity Validation: Provides the highest possible confidence that a strategy that performs as expected on the R instance will perform as expected on the W instance.
  • Reduces "It Worked on My Machine" Errors: Eliminates a whole class of bugs that arise from differences between testing and production environments.
  • Simplifies Promotion Process: The process of "promoting" a change to live becomes much simpler and safer. If it passes on R, it's ready for W (potentially with a gradual rollout using liveRatio).

Negative:

  • Inflexibility in Testing: The R instance cannot be used for ad-hoc testing of experimental features or different configurations. That is the purpose of local development environments or potentially other, temporary test instances.
  • Dependency on Testnet Quality: The quality of our validation is dependent on the quality and fidelity of the exchange's testnet API. If the testnet behaves differently from the live API (e.g., in terms of rate limits, order fill logic), our validation will be less accurate.

Mitigation:

  • Disciplined Process: We must be disciplined about not introducing one-off changes or "temporary hacks" to the R instance's configuration. It must always mirror W.
  • Documentation and Monitoring: We will document any known discrepancies between the testnet and live APIs. We will also monitor the R instance for any behavior that deviates unexpectedly from W, which could indicate a change in the testnet environment.
  • Separate Environments for Experimentation: True experimentation should be done on local developer machines or in dedicated, short-lived "staging" environments, not on the canonical R instance.