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

### 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.