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.

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/*
backend.apps.openclaw_service	8004	Read-only OpenClaw REST facade
Gateway (backend.main)	8765	WebSocket feed, runtime event stream, legacy/compat orchestration path
OpenClaw Gateway	18789	External OpenClaw WebSocket endpoint consumed by 大时代 gateway

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

It does not start openclaw_service on 8004.

Instead, the gateway 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
python -m backend.main --mode live --host 0.0.0.0 --port 8765

Optional OpenClaw REST surface:

python -m uvicorn backend.apps.openclaw_service:app --host 0.0.0.0 --port 8004 --reload

Runtime Responsibilities

The runtime path is intentionally split:

• runtime_service handles start, stop, restart, current runtime info, logs, and runtime state APIs
• agent_service handles control-plane reads and writes for agents, workspaces, files, and approvals
• backend.main / gateway hosts the live WebSocket channel and coordinates market service, scheduler, and pipeline execution

The practical request path looks like:

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

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

Note that OPENCLAW_SERVICE_URL currently points at the OpenClaw gateway origin used by the live WebSocket bridge, not the optional REST app on :8004.

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

There are two separate OpenClaw integration surfaces in this repo:

• OpenClaw WebSocket gateway on :18789
  • used directly by backend/services/gateway.py
  • this is what start-dev.sh assumes exists
• backend.apps.openclaw_service on :8004
  • optional REST facade over OpenClaw CLI-backed reads
  • useful for typed client access and service-level testing

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

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

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

backend.apps.openclaw_service
  └─ optional OpenClaw REST facade

backend.main / backend.services.gateway
  └─ live orchestration, feed transport, scheduler, runtime coordination