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

```bash
./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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```text
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
```