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

Residual Inventory

The remaining migration-related surfaces now fall into three buckets.

1. Remove When Replaced

These should not grow further. Keep them only until a concrete replacement is fully in use.

• backend.agents.compat
  • removed after the package root stopped exporting compat helpers

Recommended next action:

• keep future EvoAgent cutover work on explicit run-scoped constructors rather than reintroducing generic workspace-loading entrypoints on TradingPipeline.

2. Keep As Stable Compatibility Surfaces

These still have an operational reason to exist and should be documented rather than treated as accidental leftovers.

• backend.main
  • compatibility gateway/runtime process
  • still relevant for websocket transport and current deploy topology
• runs/<run_id>/team_dashboard/*.json
  • export/consumer compatibility layer
• gateway-mediated websocket/event flow
  • still the practical live event contract for the frontend

Recommended next action:

• keep these, but document them as intentional compatibility surfaces with explicit ownership.

3. Defer Until Topology Decisions Are Final

These are real migration boundaries, but removing them prematurely would create churn without simplifying the current runtime.

• workspaces/ design-time registry versus runs/<run_id>/ runtime state
• env-dependent service fallback behavior
• checked-in deployment docs centered on backend.main
• dual OpenClaw shapes: gateway integration and REST facade

Recommended next action:

• revisit these only after production topology and service-routing policy are frozen.