evotraders/services/README.md

大时代 Service Surfaces

This repository is in a split-first state: local development now assumes separate app surfaces and a dedicated WebSocket gateway instead of a single combined backend entrypoint.

For the canonical architecture summary, start with docs/current-architecture.md. This file is service-focused and includes migration details. The matching visual diagram lives at docs/current-architecture.excalidraw, and the next-step execution plan lives at docs/development-roadmap.md.

Service Map

Surface	Default port	Role
backend.apps.agent_service	8000	Control plane for workspaces, agents, skills, guard/approvals
backend.apps.trading_service	8001	Read-only trading data APIs such as prices, financials, insider trades
backend.apps.news_service	8002	Read-only explain/news APIs such as story, similar days, range explain
backend.apps.runtime_service	8003	Runtime lifecycle APIs under /api/runtime/*
Gateway process	8765	WebSocket feed, runtime event stream, pipeline execution
OpenClaw Gateway	18789	External OpenClaw WebSocket endpoint consumed by 大时代 gateway

Runtime Mode

For development and service isolation:

./start-dev.sh

Today this script starts the split services and then relies on runtime_service to spawn the Gateway during startup.

What Runs By Default In Dev

The supported local dev path is:

./start-dev.sh

That script starts:

• agent_service on 8000
• trading_service on 8001
• news_service on 8002
• runtime_service on 8003
• 大时代 gateway on 8765 (spawned by runtime_service)

It also expects an OpenClaw WebSocket server to already be available at ws://localhost:18789 unless you override the OpenClaw gateway configuration outside the script.

Manual Startup

Run split service surfaces explicitly:

python -m uvicorn backend.apps.agent_service:app --host 0.0.0.0 --port 8000 --reload
python -m uvicorn backend.apps.trading_service:app --host 0.0.0.0 --port 8001 --reload
python -m uvicorn backend.apps.news_service:app --host 0.0.0.0 --port 8002 --reload
python -m uvicorn backend.apps.runtime_service:app --host 0.0.0.0 --port 8003 --reload

If you launch only the split FastAPI surfaces manually, runtime_service can start the Gateway via the /api/runtime/start API. To start a runtime in that fully managed flow:

curl -X POST http://localhost:8003/api/runtime/start \
  -H "Content-Type: application/json" \
  -d '{
    "launch_mode": "fresh",
    "tickers": ["AAPL", "MSFT"],
    "schedule_mode": "daily",
    "trigger_time": "09:30",
    "initial_cash": 100000
  }'

Runtime Responsibilities

The runtime path is intentionally split:

Control Plane (runtime_service :8003)

• Gateway lifecycle: Start, stop, restart Gateway processes
• Configuration: Bootstrap values, runtime parameters
• Health monitoring: Gateway process status, port management
• Run history: List historical runs, restore from snapshots

Data Plane (Gateway :8765)

• WebSocket transport: Live event streaming to frontend
• Pipeline execution: Analysis -> Communication -> Decision -> Execution
• Market data: Real-time price feeds and backtest simulation
• Scheduler: Trading cycle orchestration

Supporting Services

• agent_service handles control-plane reads and writes for agents, workspaces, files, and approvals
• trading_service provides read-only trading data
• news_service provides news enrichment and explanation APIs

The practical request path looks like:

frontend -> runtime_service/control APIs -> gateway/runtime manager -> market service + pipeline + storage

runtime_service as Gateway Process Manager

The runtime_service is the Gateway Process Manager in the microservice architecture. Its responsibilities:

1. Process Management

   • Spawns Gateway as subprocess via _start_gateway_process()
   • Monitors process health via gateway_process.poll()
   • Handles graceful shutdown (SIGTERM) and force kill

2. Port Management

   • Finds available ports (_find_available_port())
   • Tracks current Gateway port in RuntimeState

3. Lifecycle APIs

   • POST /api/runtime/start - Create run, spawn Gateway
   • POST /api/runtime/stop - Stop Gateway process
   • POST /api/runtime/restart - Stop then start new runtime
   • GET /api/runtime/gateway/status - Check Gateway health

4. State Management

   • Maintains RuntimeState singleton (thread-safe)
   • Tracks runtime_manager reference for in-memory state
   • Falls back to persisted snapshots when Gateway is stopped

Gateway Subprocess Architecture

runtime_service (:8003)
    |
    |-- can spawn --> Gateway subprocess (:8765)
                       |
                       |-- TradingPipeline
                       |-- MarketService
                       |-- Scheduler
                       |-- WebSocket server

The Gateway subprocess runs backend.gateway_server with run-specific configuration passed by runtime_service.

Environment Variables

Backend routing preferences

These variables let the gateway or tools prefer split services over in-process fallbacks:

Variable	Used by	Meaning
TRADING_SERVICE_URL	gateway, data tools	Prefer trading_service for trading reads
NEWS_SERVICE_URL	gateway, data tools	Prefer news_service for explain/news reads
RUNTIME_SERVICE_URL	dev scripts / future follow-up	Reserved for runtime-service-aware flows
OPENCLAW_SERVICE_URL	dev scripts / future follow-up	Points at the OpenClaw gateway origin in current dev setup

Current start-dev.sh defaults:

TRADING_SERVICE_URL=http://localhost:8001
NEWS_SERVICE_URL=http://localhost:8002
RUNTIME_SERVICE_URL=http://localhost:8003
OPENCLAW_SERVICE_URL=http://localhost:18789

Frontend service targets

The frontend can directly call split services with:

VITE_CONTROL_API_BASE_URL=http://localhost:8000/api
VITE_RUNTIME_API_BASE_URL=http://localhost:8003/api/runtime
VITE_NEWS_SERVICE_URL=http://localhost:8002
VITE_TRADING_SERVICE_URL=http://localhost:8001
VITE_WS_URL=ws://localhost:8765

Current Frontend Direct-Call Coverage

Direct browser calls currently cover:

• runtime panel loading and runtime discovery
• story
• similar days
• range explain
• news for date
• news categories
• selected trading reads such as stock history and insider trades

Other flows still depend on the gateway WebSocket and control plane APIs.

OpenClaw Integration Notes

OpenClaw currently appears through two concrete access patterns in this repo:

• OpenClaw WebSocket gateway on :18789
  • used directly by backend/services/gateway.py
  • this is what start-dev.sh assumes exists
• selected CLI-backed read helpers behind gateway handlers
  • used for a small set of history/status style reads
  • not a separate standalone REST service surface

Do not treat those as interchangeable in docs or deployment config.

Internal Module Direction

The codebase is now organized around these boundaries:

frontend
  ├─ runtime/control/news/trading API clients
  └─ WebSocket runtime feed

backend.apps.agent_service
  └─ control-plane routes

backend.apps.runtime_service
  └─ runtime lifecycle routes, Gateway process management

backend.apps.trading_service
  └─ read-only trading contract

backend.apps.news_service
  └─ read-only explain/news contract


backend.gateway_server
  └─ Gateway subprocess entry point (run-scoped)

Migration Boundaries

Some agent-migration helpers still exist in the tree, but they are not part of the supported runtime path yet:

No workspace-loading helper remains on TradingPipeline. Runtime agent loading is expected to stay on the run-scoped creation path.

Also note the remaining naming split:

• workspaces/ = design-time CRUD registry
• runs/<run_id>/ = runtime state and run-scoped agent assets

Future Architecture Direction

Current State

• Pipeline logic lives in Gateway process
• Gateway is spawned as subprocess by runtime_service
• Historical direct gateway startup has been removed from the repository

Target State

• Pipeline stages become independent services
• Gateway becomes thin event router
• runtime_service becomes full orchestrator
• Keep converging on the split-service startup model

See docs/development-roadmap.md for detailed phase planning.