stock-bot/docs/current-system-flow.md

# 🔄 Current System Communication Flow

## Active Services (Currently Running)

```mermaid
graph TB
    %% External Data Sources
    subgraph "External APIs"
        EXT[Demo Data Generation<br/>Alpha Vantage Ready<br/>Yahoo Finance Ready]
    end

    %% Currently Active Services
    subgraph "Active Services"
        MDG[Market Data Gateway<br/>Port 3001<br/>✅ Running]
        TD[Trading Dashboard<br/>Port 5173<br/>✅ Running]
    end

    %% Storage Layer
    subgraph "Storage"
        DRAGONFLY[(Dragonfly<br/>📡 Events & Cache<br/>🔧 Configured)]
    end

    %% Data Flow
    EXT -->|HTTP Fetch| MDG
    MDG -->|REST API| TD
    MDG -->|WebSocket Stream| TD
    MDG -->|Events| DRAGONFLY
    
    %% Styling
    classDef active fill:#90EE90
    classDef storage fill:#FFE4B5
    classDef external fill:#FFB6C1
    
    class MDG,TD active
    class DRAGONFLY storage
    class EXT external
```

## Next Phase Services (Ready to Implement)

```mermaid
graph TB
    %% Current Services
    subgraph "Current Layer"
        MDG[Market Data Gateway<br/>✅ Operational]
        TD[Trading Dashboard<br/>✅ Operational]
    end

    %% Next Phase Services  
    subgraph "Next Phase - Priority 1"
        SO[Strategy Orchestrator<br/>🚧 Package Created<br/>📋 Ready to Implement]
        RG[Risk Guardian<br/>🚧 Package Created<br/>📋 Ready to Implement]
    end

    %% Communication Infrastructure
    subgraph "Event Infrastructure"
        DRAGONFLY[(Dragonfly Streams<br/>✅ Configured)]
        WS[WebSocket Server<br/>✅ Active in MDG]
    end

    %% Data Flows
    MDG -->|Market Data Events| DRAGONFLY
    MDG -->|Real-time Stream| WS
    WS -->|Live Updates| TD
      DRAGONFLY -->|Market Events| SO
    DRAGONFLY -->|All Events| RG
    
    SO -->|Strategy Events| DRAGONFLY
    SO -->|Risk Check| RG
    RG -->|Risk Alerts| DRAGONFLY
    
    %% Styling
    classDef current fill:#90EE90
    classDef next fill:#FFE4B5
    classDef infrastructure fill:#E6E6FA
    
    class MDG,TD current
    class SO,RG next
    class DRAGONFLY,WS infrastructure
```

## Detailed Communication Patterns

### 1. **Current System (Working)**

```
┌─────────────────┐    HTTP REST    ┌─────────────────┐
│ Trading         │ ←──────────────→ │ Market Data     │
│ Dashboard       │                 │ Gateway         │
│ (React/Tremor)  │ ←──────────────→ │ (Hono/Bun)     │
└─────────────────┘    WebSocket    └─────────────────┘
                                           │
                                           ▼
                                    ┌─────────────────┐
                                    │ Dragonfly Events    │
                                    │ (Configured)    │
                                    └─────────────────┘
```

### 2. **Next Phase Implementation**

```
┌─────────────────┐
│ Strategy        │
│ Orchestrator    │ ──┐
└─────────────────┘   │
                      ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Market Data     │→│ Dragonfly Event     │←│ Risk Guardian   │
│ Gateway         │ │ Stream          │ │                 │
└─────────────────┘ └─────────────────┘ └─────────────────┘
        │                   │                   │
        ▼                   ▼                   ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Trading         │ │ WebSocket       │ │ Alert Manager   │
│ Dashboard       │ │ Real-time       │ │ (Future)        │
└─────────────────┘ └─────────────────┘ └─────────────────┘
```

## Event Flow Diagram

```mermaid
sequenceDiagram
    participant TD as Trading Dashboard
    participant MDG as Market Data Gateway
    participant DRAGONFLY as Dragonfly Events
    participant SO as Strategy Orchestrator (Next)
    participant RG as Risk Guardian (Next)

    Note over TD,DRAGONFLY: Current System - Working

    MDG->>MDG: Generate demo market data
    MDG->>TD: WebSocket real-time updates
    MDG->>DRAGONFLY: Publish MARKET_DATA events
    TD->>MDG: HTTP API requests
    MDG->>TD: JSON responses

    Note over SO,RG: Next Phase - To Implement

    DRAGONFLY->>SO: Subscribe to MARKET_DATA events
    SO->>SO: Analyze market conditions
    SO->>DRAGONFLY: Publish SIGNAL_GENERATED events
    
    DRAGONFLY->>RG: Subscribe to ALL events
    RG->>RG: Monitor risk thresholds
    RG->>DRAGONFLY: Publish RISK_ALERT events
    
    DRAGONFLY->>TD: All events via WebSocket
    TD->>TD: Update dashboard with alerts
```

## Service Dependencies

### **Current Dependencies (Satisfied)**
```
Market Data Gateway
├── ✅ Hono (Web framework)
├── ✅ ioredis (Redis client)  
├── ✅ @stock-bot/config (Workspace package)
├── ✅ @stock-bot/types (Workspace package)
└── ✅ ws (WebSocket library)

Trading Dashboard  
├── ✅ React + TypeScript
├── ✅ Tremor UI (Financial components)
├── ✅ Vite (Build tool)
└── ✅ WebSocket client
```

### **Next Phase Dependencies (Ready)**
```
Strategy Orchestrator
├── ✅ Package.json created
├── ✅ Dependencies specified
├── 📋 Implementation needed
└── 🔧 node-cron (Strategy scheduling)

Risk Guardian
├── ✅ Package.json created  
├── ✅ Dependencies specified
├── 📋 Implementation needed
└── 🛡️ Risk monitoring logic
```

## Port & Endpoint Map

| Service | Port | Endpoints | Status |
|---------|------|-----------|--------|
| **Market Data Gateway** | 3001 | `/health`, `/api/market-data/:symbol`, `/api/ohlcv/:symbol`, WebSocket | ✅ Active |
| **Trading Dashboard** | 5173 | Vite dev server | ✅ Active |
| **Strategy Orchestrator** | 4001 | `/health`, `/api/strategies`, `/api/signals` | 📋 Planned |
| **Risk Guardian** | 3002 | `/health`, `/api/risk-checks`, `/api/limits` | 📋 Planned |

## Data Types & Events

### **Market Data Event**
```typescript
interface MarketDataEvent {
  type: 'MARKET_DATA';
  data: {
    symbol: string;
    price: number;
    bid: number;
    ask: number;
    volume: number;
    timestamp: Date;
  };
  timestamp: Date;
}
```

### **Strategy Event (Next Phase)**
```typescript
interface StrategyEvent {
  type: 'SIGNAL_GENERATED' | 'STRATEGY_START' | 'STRATEGY_STOP';
  strategyId: string;
  signal?: TradingSignal;
  timestamp: Date;
}
```

### **Risk Event (Next Phase)**
```typescript
interface RiskEvent {
  type: 'RISK_ALERT' | 'RISK_CHECK';
  severity: 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL';
  message: string;
  data: any;
  timestamp: Date;
}
```

This architecture shows how your current working system will expand into a comprehensive trading platform with clear communication patterns and event flows.