161 lines
5.3 KiB
Markdown
161 lines
5.3 KiB
Markdown
# 大时代 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
|
|
```
|