117 lines
4.1 KiB
Markdown
117 lines
4.1 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`
|
|
- 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
|