164 lines
5.6 KiB
Markdown
164 lines
5.6 KiB
Markdown
# 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.
|