# EvoTraders Services Architecture

This repo is currently in a **migration state** between a modular monolith and
fully split services. Service boundaries now exist as dedicated FastAPI app
surfaces, and local development now runs those split services directly.

## Current App Surfaces

| App surface | Default port | Responsibility |
| --- | --- | --- |
| `backend.apps.agent_service` | 8000 | Control-plane only: workspaces, agents, guard. |
| `backend.apps.runtime_service` | 8003 | Runtime lifecycle only: `/api/runtime/*`. |
| `backend.apps.trading_service` | 8001 | Read-only trading data: prices, financials, insider trades, market status, market cap. |
| `backend.apps.news_service` | 8002 | Read-only explain/news data: enriched news, categories, story, similar days, range explain. |

## Local Development Modes

### 1. Split-service mode

This is now the default development mode.

```bash
./start-dev.sh

# explicit
./start-dev.sh split
```

Run dedicated service surfaces explicitly:

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

## Migration Variables

These env vars control whether the app still uses local-module fallbacks or
prefers service boundaries:

| Variable | Used by | Purpose |
| --- | --- | --- |
| `NEWS_SERVICE_URL` | backend Gateway | Prefer `news-service` for explain/news read paths |
| `TRADING_SERVICE_URL` | backend Gateway | Prefer `trading-service` for trading read paths |
| `RUNTIME_SERVICE_URL` | reserved | Future runtime/control-plane split follow-up |
| `VITE_NEWS_SERVICE_URL` | frontend | Direct browser calls to `news-service` for selected explain paths |
| `VITE_TRADING_SERVICE_URL` | frontend | Reserved for future direct trading reads |

If these are empty, the repo keeps using local module fallbacks where they still exist.

## Current Internal Direction

The repository is now organized around split service surfaces:

```text
frontend
  ├─ runtime/control/news/trading split endpoints
  └─ selective per-request fallbacks where still retained

backend.apps.agent_service
  └─ control-plane routes

backend.apps.runtime_service
  └─ runtime lifecycle + gateway discovery

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

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