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

• These are both valid, but they are not the same surface and should not be documented as interchangeable.

Remaining Migration Risks

Checked-in deployment artifacts still lag the development topology

• The repo documents split-service local development clearly.
• The checked-in deployment docs still center on historical nginx WebSocket proxying rather than the active dev topology.
• 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. Deployment docs and scripts explicitly run the same split-service topology used in development, or are removed from the repo.
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 small set of CLI-backed gateway read helpers.
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.

• 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 only surfaces with an active operational consumer, and avoid routing new development through them.

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 that have not yet been rewritten around split services
• dual OpenClaw access patterns: gateway integration and CLI-backed read helpers

Recommended next action:

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