evotraders/docs/compat-removal-plan.md

Compatibility And Migration Status

This document tracks the remaining migration-related boundaries after the repository switched to split-first development.

Current Status

The repo no longer depends on a combined FastAPI compatibility wrapper for normal local development. The default path is now:

agent_service + trading_service + news_service + runtime_service + gateway

That means compatibility is no longer a separate startup mode. What remains is mostly protocol-level and routing-level compatibility while the codebase continues to move responsibilities into clearer service surfaces.

What Was Removed

backend.app

• Removed after startup paths switched away from the legacy app wrapper.

backend.apps.combined_service

• Removed after split-service startup became the only supported local dev mode.

shared.client.AgentServiceClient

• Removed after split-aware clients became the default import surface.
• Replaced by:
  • ControlPlaneClient
  • RuntimeServiceClient
  • TradingServiceClient
  • NewsServiceClient

What Still Exists For Compatibility

These are not legacy wrappers in the old sense, but they still preserve backward-compatible behavior while migration settles.

Gateway-mediated flows

• The WebSocket gateway still carries a mix of:
  • live runtime feed transport
  • orchestration
  • selected read flows that have not been moved to direct browser service calls
• This is intentional for now because the frontend still depends on the gateway for event streaming and some compatibility reads.

In-process fallbacks

• Some read paths still support local-module fallback when split-service URLs are not configured.
• Relevant variables include:
  • TRADING_SERVICE_URL
  • NEWS_SERVICE_URL
• This keeps the app resilient during migration, but it also means behavior can differ depending on env configuration.

Dual OpenClaw integration surfaces

• OpenClaw currently appears through two different shapes:
  • WebSocket gateway integration on :18789
  • optional REST surface at backend.apps.openclaw_service on :8004
• These are both valid, but they are not the same surface and should not be documented as interchangeable.

Remaining Migration Risks

Split service deployment is not yet the checked-in production default

• The repo documents split-service local development clearly.
• The checked-in production example still centers on backend.main and nginx WebSocket proxying.
• This is a topology mismatch to keep in mind when changing deploy docs or prod automation.

Environment-dependent routing

• The frontend and gateway can switch behavior based on configured service URLs.
• This is helpful operationally, but it makes debugging more configuration- sensitive than a fully fixed service topology.

Runtime/control-plane separation is logical, not fully operationally isolated

• runtime_service owns lifecycle APIs.
• agent_service owns control-plane APIs.
• The gateway still hosts the live runtime orchestration path, so the split is clean at the API level but not yet a completely independent service mesh.

Exit Criteria For Declaring Migration Complete

Migration can be considered effectively complete when all of the following are true:

1. Production deployment docs and scripts explicitly run the same split-service topology used in development, or intentionally document a different stable production topology.
2. Critical read paths no longer require ambiguous fallback behavior to local module implementations.
3. OpenClaw integration is documented as a stable contract with clear guidance on when to use the WebSocket gateway versus the REST surface.
4. The frontend-service routing model is stable enough that direct-service and gateway-mediated paths are deliberate design choices rather than migration leftovers.

Practical Read Of The Current State

The migration away from combined-service startup is done.

What remains is not “legacy startup debt”, but:

• topology clarification
• deployment consistency
• reduction of env-dependent fallback behavior
• sharper documentation around gateway and OpenClaw boundaries