adding data-services

docs/websocket-api.md

@@ -0,0 +1,247 @@
+# WebSocket API Documentation - Strategy Orchestrator
+
+## Overview
+
+This document outlines the WebSocket API provided by the Strategy Orchestrator service for real-time communication between the backend and frontend.
+
+## Connection Endpoints
+
+- **Strategy Orchestrator WebSocket:** `ws://localhost:8082`
+- **Market Data Gateway WebSocket:** `ws://localhost:3001/ws`
+- **Risk Guardian WebSocket:** `ws://localhost:3002/ws`
+
+## Message Format
+
+All WebSocket messages follow this standard format:
+
+```json
+{
+  "type": "message_type",
+  "timestamp": "ISO-8601 timestamp",
+  "data": {
+    // Message-specific data
+  }
+}
+```
+
+## Client to Server Messages
+
+### Get Active Strategies
+
+Request information about all active strategies.
+
+```json
+{
+  "type": "get_active_strategies"
+}
+```
+
+### Start Strategy
+
+Start a specific strategy.
+
+```json
+{
+  "type": "start_strategy",
+  "id": "strategy-id",
+  "config": {
+    "symbols": ["AAPL", "MSFT"],
+    "dataResolution": "1m",
+    "realTrading": false,
+    "maxPositionValue": 10000,
+    "maxOrdersPerMinute": 5,
+    "stopLossPercentage": 0.02
+  }
+}
+```
+
+### Stop Strategy
+
+Stop a running strategy.
+
+```json
+{
+  "type": "stop_strategy",
+  "id": "strategy-id"
+}
+```
+
+### Pause Strategy
+
+Pause a running strategy.
+
+```json
+{
+  "type": "pause_strategy",
+  "id": "strategy-id"
+}
+```
+
+## Server to Client Messages
+
+### Strategy Status List
+
+Response to `get_active_strategies` request.
+
+```json
+{
+  "type": "strategy_status_list",
+  "timestamp": "2023-07-10T12:34:56Z",
+  "data": [
+    {
+      "id": "strategy-123",
+      "name": "Moving Average Crossover",
+      "status": "ACTIVE",
+      "symbols": ["AAPL", "MSFT"],
+      "positions": [
+        {
+          "symbol": "AAPL",
+          "quantity": 10,
+          "entryPrice": 150.25,
+          "currentValue": 1550.50
+        }
+      ]
+    }
+  ]
+}
+```
+
+### Strategy Started
+
+Notification that a strategy has been started.
+
+```json
+{
+  "type": "strategy_started",
+  "timestamp": "2023-07-10T12:34:56Z",
+  "data": {
+    "strategyId": "strategy-123",
+    "name": "Moving Average Crossover",
+    "symbols": ["AAPL", "MSFT"]
+  }
+}
+```
+
+### Strategy Stopped
+
+Notification that a strategy has been stopped.
+
+```json
+{
+  "type": "strategy_stopped",
+  "timestamp": "2023-07-10T12:34:56Z",
+  "data": {
+    "strategyId": "strategy-123",
+    "name": "Moving Average Crossover"
+  }
+}
+```
+
+### Strategy Paused
+
+Notification that a strategy has been paused.
+
+```json
+{
+  "type": "strategy_paused",
+  "timestamp": "2023-07-10T12:34:56Z",
+  "data": {
+    "strategyId": "strategy-123",
+    "name": "Moving Average Crossover"
+  }
+}
+```
+
+### Strategy Signal
+
+Trading signal generated by a strategy.
+
+```json
+{
+  "type": "strategy_signal",
+  "timestamp": "2023-07-10T12:34:56Z",
+  "data": {
+    "id": "sig_123456789",
+    "strategyId": "strategy-123",
+    "name": "Moving Average Crossover",
+    "symbol": "AAPL",
+    "price": 152.75,
+    "action": "BUY",
+    "quantity": 10,
+    "metadata": { "orderType": "MARKET" },
+    "timestamp": "2023-07-10T12:34:56Z",
+    "confidence": 0.9
+  }
+}
+```
+
+### Strategy Trade
+
+Notification of a trade executed by a strategy.
+
+```json
+{
+  "type": "strategy_trade",
+  "timestamp": "2023-07-10T12:34:56Z",
+  "data": {
+    "id": "trade_123456789",
+    "strategyId": "strategy-123",
+    "orderId": "order-123",
+    "symbol": "AAPL",
+    "side": "BUY",
+    "quantity": 10,
+    "entryPrice": 152.75,
+    "entryTime": "2023-07-10T12:34:56Z",
+    "status": "FILLED",
+    "timestamp": "2023-07-10T12:34:56Z"
+  }
+}
+```
+
+### Execution Service Status
+
+Notification about the overall execution service status.
+
+```json
+{
+  "type": "execution_service_status",
+  "timestamp": "2023-07-10T12:34:56Z",
+  "data": {
+    "status": "RUNNING" // or "STOPPED"
+  }
+}
+```
+
+## Frontend Integration
+
+The frontend can use the `WebSocketService` to interact with the WebSocket API:
+
+```typescript
+// Subscribe to strategy signals
+webSocketService.getStrategySignals(strategyId)
+  .subscribe(signal => {
+    // Handle the signal
+  });
+
+// Subscribe to strategy trades
+webSocketService.getStrategyTrades(strategyId)
+  .subscribe(trade => {
+    // Handle the trade
+  });
+
+// Subscribe to strategy status updates
+webSocketService.getStrategyUpdates()
+  .subscribe(update => {
+    // Handle the update
+  });
+```
+
+## Error Handling
+
+WebSocket connections will automatically attempt to reconnect if disconnected. The frontend can monitor connection status using:
+
+```typescript
+webSocketService.isConnected() // Returns a boolean signal indicating connection status
+```
+
+If a WebSocket message fails to process, the error will be logged, but the connection will be maintained.