大时代 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