# Psyche Domain: Communication Architecture

This document details the inter-service communication patterns in the Serwaa
codebase (to be migrated to the Psyche domain).

## Communication Overview

Serwaa uses a multi-protocol communication architecture optimized for real-time
AI avatar interactions:

| Protocol      | Latency | Use Case                              |
| ------------- | ------- | ------------------------------------- |
| REST/HTTP     | <50ms   | CRUD operations, client API           |
| WebSocket     | <20ms   | Real-time client events, streaming    |
| gRPC Streams  | <10ms   | Service-to-service, audio/video       |
| Redis Pub/Sub | <5ms    | Event broadcasting, state sync        |
| Redis Streams | <5ms    | Async event processing, message queue |

---

## 1. REST APIs

### API Gateway Endpoints

The API Gateway (`services/api-gateway/`) provides the primary REST interface.

#### Sessions Management

| Method | Endpoint                             | Description           |
| ------ | ------------------------------------ | --------------------- |
| POST   | `/api/v1/sessions`                   | Create new session    |
| GET    | `/api/v1/sessions`                   | List sessions         |
| GET    | `/api/v1/sessions/{id}`              | Get session details   |
| POST   | `/api/v1/sessions/{id}/start`        | Start pending session |
| POST   | `/api/v1/sessions/{id}/join-meeting` | Join video conference |
| POST   | `/api/v1/sessions/{id}/pause`        | Pause session         |
| POST   | `/api/v1/sessions/{id}/resume`       | Resume session        |
| POST   | `/api/v1/sessions/{id}/end`          | End session           |
| DELETE | `/api/v1/sessions/{id}`              | Delete session        |
| GET    | `/api/v1/sessions/metrics`           | Get session metrics   |

**Session Create Request:**

```json
{
  "persona_id": "uuid",
  "meeting_url": "https://zoom.us/j/...",
  "platform": "zoom",
  "config": {
    "auto_join": true,
    "record": false
  },
  "metadata": {}
}
```

**Session State Transitions:**

```
PENDING → CONNECTING → ACTIVE → PAUSED → ACTIVE → ENDED
                              └──────────────────────────┘
```

#### Personas Management

| Method | Endpoint                           | Description        |
| ------ | ---------------------------------- | ------------------ |
| POST   | `/api/v1/personas`                 | Create persona     |
| GET    | `/api/v1/personas`                 | List personas      |
| GET    | `/api/v1/personas/{id}`            | Get persona        |
| PATCH  | `/api/v1/personas/{id}`            | Update persona     |
| DELETE | `/api/v1/personas/{id}`            | Delete persona     |
| POST   | `/api/v1/personas/{id}/activate`   | Activate persona   |
| POST   | `/api/v1/personas/{id}/deactivate` | Deactivate persona |
| POST   | `/api/v1/personas/{id}/clone`      | Clone persona      |

**Persona Create Request:**

```json
{
  "name": "Sales Assistant",
  "description": "Professional sales persona",
  "system_prompt": "You are a helpful sales assistant...",
  "personality": {
    "openness": 0.7,
    "conscientiousness": 0.8,
    "extraversion": 0.6,
    "agreeableness": 0.9,
    "neuroticism": 0.2
  },
  "voice": {
    "voice_id": "elevenlabs_voice_id",
    "speed": 1.0,
    "pitch": 1.0
  },
  "avatar": {
    "model_id": "avatar_model_id",
    "appearance": {}
  },
  "expertise": ["sales", "product-knowledge"]
}
```

#### Knowledge Base Management

| Method | Endpoint                                     | Description        |
| ------ | -------------------------------------------- | ------------------ |
| POST   | `/api/v1/knowledge/documents`                | Create document    |
| POST   | `/api/v1/knowledge/documents/upload`         | Upload file        |
| GET    | `/api/v1/knowledge/documents`                | List documents     |
| GET    | `/api/v1/knowledge/documents/{id}`           | Get document       |
| PATCH  | `/api/v1/knowledge/documents/{id}`           | Update metadata    |
| DELETE | `/api/v1/knowledge/documents/{id}`           | Delete document    |
| POST   | `/api/v1/knowledge/documents/{id}/reprocess` | Reprocess document |
| POST   | `/api/v1/knowledge/search`                   | Semantic search    |

**Supported Document Types:**

- PDF (`.pdf`)
- Word (`.docx`, `.doc`)
- HTML (`.html`, `.htm`)
- Markdown (`.md`)
- CSV (`.csv`)
- JSON (`.json`)
- Plain Text (`.txt`)

**Search Request:**

```json
{
  "query": "product pricing information",
  "persona_id": "uuid",
  "tags": ["pricing", "products"],
  "top_k": 10
}
```

#### Tools Management

| Method | Endpoint                        | Description     |
| ------ | ------------------------------- | --------------- |
| POST   | `/api/v1/tools`                 | Register tool   |
| GET    | `/api/v1/tools`                 | List tools      |
| GET    | `/api/v1/tools/{id}`            | Get tool        |
| PATCH  | `/api/v1/tools/{id}`            | Update tool     |
| DELETE | `/api/v1/tools/{id}`            | Delete tool     |
| POST   | `/api/v1/tools/{id}/test`       | Test execution  |
| POST   | `/api/v1/tools/{id}/activate`   | Activate tool   |
| POST   | `/api/v1/tools/{id}/deactivate` | Deactivate tool |
| GET    | `/api/v1/tools/{id}/schema`     | Get JSON schema |

**Tool Types:**

- `function` - Internal Python functions
- `api` - External REST APIs
- `mcp` - Model Context Protocol servers
- `webhook` - HTTP webhooks

#### Learning System API

| Method | Endpoint                     | Description           |
| ------ | ---------------------------- | --------------------- |
| GET    | `/health`                    | Health check          |
| POST   | `/memory`                    | Add memory block      |
| GET    | `/memory/{block_id}`         | Get memory block      |
| POST   | `/memory/search`             | Search memories       |
| GET    | `/memory/context`            | Get context window    |
| GET    | `/tools`                     | List memory tools     |
| POST   | `/tools/execute`             | Execute memory tool   |
| POST   | `/session/start`             | Start user session    |
| POST   | `/session/{id}/end`          | End session           |
| GET    | `/session/{user_id}/restore` | Restore context       |
| GET    | `/decay/status`              | Decay status          |
| POST   | `/consolidate`               | Trigger consolidation |

---

## 2. WebSocket Connections

### Connection Endpoints

```
ws://host:8000/api/v1/ws                        # General endpoint
ws://host:8000/api/v1/ws/sessions/{session_id}  # Session-specific
```

Query parameters:

- `token` - Authentication token (optional)

### Message Types

#### Client → Server Messages

**Subscribe Message:**

```json
{
  "type": "subscribe",
  "session_id": "session_123",
  "events": ["session.started", "session.ended", "conversation.message"]
}
```

**Unsubscribe Message:**

```json
{
  "type": "unsubscribe",
  "session_id": "session_123"
}
```

**Command Message:**

```json
{
  "type": "command",
  "id": "cmd_001",
  "session_id": "session_123",
  "command": "session.pause",
  "parameters": {}
}
```

**Ping Message:**

```json
{
  "type": "ping",
  "timestamp": "2024-01-24T12:00:00Z"
}
```

#### Server → Client Events

**Session Events:**

| Event Type            | Description            |
| --------------------- | ---------------------- |
| SESSION_STARTED       | Session became active  |
| SESSION_ENDED         | Session terminated     |
| SESSION_PAUSED        | Session paused         |
| SESSION_RESUMED       | Session resumed        |
| SESSION_ERROR         | Session error occurred |
| SESSION_STATE_CHANGED | State transition       |

**Meeting Events:**

| Event Type                 | Description             |
| -------------------------- | ----------------------- |
| MEETING_JOINING            | Attempting to join      |
| MEETING_JOINED             | Successfully joined     |
| MEETING_LEFT               | Left meeting            |
| MEETING_PARTICIPANT_JOINED | Participant joined      |
| MEETING_PARTICIPANT_LEFT   | Participant left        |
| MEETING_AUDIO_STARTED      | Audio streaming started |
| MEETING_VIDEO_STARTED      | Video streaming started |

**Conversation Events:**

| Event Type                | Description             |
| ------------------------- | ----------------------- |
| CONVERSATION_TURN_STARTED | Speaking turn started   |
| CONVERSATION_TURN_ENDED   | Speaking turn ended     |
| CONVERSATION_MESSAGE      | Message in conversation |

**AI State Events:**

| Event Type   | Description             |
| ------------ | ----------------------- |
| AI_THINKING  | Processing input        |
| AI_SPEAKING  | Generating speech       |
| AI_LISTENING | Listening for input     |
| AI_IDLE      | Waiting for interaction |

**Tool Events:**

| Event Type     | Description             |
| -------------- | ----------------------- |
| TOOL_EXECUTING | Tool being executed     |
| TOOL_COMPLETED | Tool execution complete |
| TOOL_ERROR     | Tool execution failed   |

**Emotion Events:**

| Event Type        | Description              |
| ----------------- | ------------------------ |
| EMOTION_DETECTED  | Emotion recognized       |
| SENTIMENT_CHANGED | Sentiment shift detected |

**Transcript Event:**

```json
{
  "type": "transcript",
  "session_id": "session_123",
  "speaker_id": "participant_001",
  "speaker_name": "John Doe",
  "text": "Hello, how are you?",
  "start_time": 1234567890.123,
  "end_time": 1234567892.456,
  "confidence": 0.95,
  "is_final": true,
  "language": "en"
}
```

**Metrics Event:**

```json
{
  "type": "metrics",
  "session_id": "session_123",
  "timestamp": "2024-01-24T12:00:00Z",
  "metrics": {
    "latency_ms": 45,
    "tokens_used": 150,
    "audio_buffer_size": 0.5
  }
}
```

### Command Types

| Command            | Description             |
| ------------------ | ----------------------- |
| START_SESSION      | Start session           |
| PAUSE_SESSION      | Pause session           |
| RESUME_SESSION     | Resume session          |
| END_SESSION        | End session             |
| MUTE_AUDIO         | Mute microphone         |
| UNMUTE_AUDIO       | Unmute microphone       |
| ENABLE_VIDEO       | Enable camera           |
| DISABLE_VIDEO      | Disable camera          |
| START_SCREEN_SHARE | Start screen sharing    |
| STOP_SCREEN_SHARE  | Stop screen sharing     |
| INTERRUPT_AI       | Interrupt AI response   |
| SET_AI_MODE        | Change AI behavior mode |
| EXECUTE_TOOL       | Execute specific tool   |
| CANCEL_TOOL        | Cancel tool execution   |
| SWITCH_PERSONA     | Switch active persona   |
| SUBSCRIBE_EVENTS   | Subscribe to events     |
| UNSUBSCRIBE_EVENTS | Unsubscribe from events |

### Connection Management

The WebSocket Connection Manager handles:

- Connection lifecycle (connect, disconnect, reconnect)
- Session subscriptions and event filtering
- Async message queues per session (default: 1000 messages)
- Connection metadata for authentication
- Selective event broadcasting

**REST Endpoints for WebSocket Management:**

| Method | Endpoint                               | Description       |
| ------ | -------------------------------------- | ----------------- |
| GET    | `/api/v1/ws/connections`               | List connections  |
| GET    | `/api/v1/ws/connections/{id}`          | Get connection    |
| GET    | `/api/v1/ws/sessions/{id}/subscribers` | Subscriber count  |
| GET    | `/api/v1/ws/stats`                     | Server statistics |

---

## 3. gRPC Services

### Architecture

The Orchestrator manages gRPC communication between services using bidirectional
streaming for low-latency data transfer.

```
┌────────────────────────────────────────────────────────┐
│                    Orchestrator                        │
│  ┌────────────────────────────────────────────────┐   │
│  │           GRPCStreamManager                     │   │
│  │  ┌─────────────┐  ┌─────────────┐              │   │
│  │  │ Connection  │  │   Stream    │              │   │
│  │  │    Pool     │  │   Manager   │              │   │
│  │  └─────────────┘  └─────────────┘              │   │
│  └────────────────────────────────────────────────┘   │
└────────────────────────────────────────────────────────┘
         │              │              │              │
    gRPC Stream    gRPC Stream    gRPC Stream    gRPC Stream
         │              │              │              │
         ▼              ▼              ▼              ▼
    ┌─────────┐   ┌─────────┐   ┌─────────┐   ┌─────────┐
    │   ASR   │   │   TTS   │   │   LLM   │   │ Avatar  │
    │ Service │   │ Service │   │ Service │   │ Service │
    └─────────┘   └─────────┘   └─────────┘   └─────────┘
```

### Service Types

| Service Type | Description                    |
| ------------ | ------------------------------ |
| ASR          | Automatic Speech Recognition   |
| TTS          | Text-to-Speech Synthesis       |
| LLM          | Language Model Inference       |
| NLU          | Natural Language Understanding |
| VISION       | Computer Vision                |
| AVATAR       | Avatar Rendering               |
| EMOTION      | Emotion Detection              |
| KNOWLEDGE    | Knowledge Base Search          |
| TOOLS        | Tool Execution                 |

### Connection States

```
CONNECTING → CONNECTED ⇄ RECONNECTING → DISCONNECTED
                 ↓
              FAILED
```

### gRPC Request/Response Models

**GRPCRequest:**

```python
class GRPCRequest:
    request_id: UUID
    service: str          # Service ID
    method: str           # Method name
    payload: bytes        # Serialized data
    metadata: dict        # Headers/context
    timeout_ms: int = 30000
    is_streaming: bool = False
    stream_id: Optional[str] = None
```

**GRPCResponse:**

```python
class GRPCResponse:
    request_id: UUID      # Correlates with request
    status_code: int      # 0 = OK, gRPC codes
    status_message: str   # OK, UNAVAILABLE, etc.
    payload: bytes        # Response data
    metadata: dict        # Response headers
    latency_ms: float     # Measured latency
    is_streaming: bool
    is_final: bool        # Last message in stream
```

### Message Types for Pipeline

| Type        | Description               |
| ----------- | ------------------------- |
| AUDIO_FRAME | Audio data (PCM/Opus/AAC) |
| VIDEO_FRAME | Video data (H264/VP8/VP9) |
| TEXT        | Text messages             |
| COMMAND     | Control commands          |
| EVENT       | Event notifications       |
| RESPONSE    | Service responses         |
| ERROR       | Error messages            |
| HEARTBEAT   | Keep-alive                |
| ACK         | Acknowledgments           |

### Stream Configuration

**Audio Stream:**

| Parameter   | Value         |
| ----------- | ------------- |
| Sample Rate | 16,000 Hz     |
| Channels    | 1 (mono)      |
| Bit Depth   | 16-bit        |
| Codec       | PCM (default) |
| Frame Size  | 20ms          |

**Video Stream:**

| Parameter         | Value     |
| ----------------- | --------- |
| Resolution        | 1280x720  |
| Frame Rate        | 30 FPS    |
| Codec             | H.264     |
| Bitrate           | 2500 kbps |
| Keyframe Interval | 60 frames |

### Stream Manager Operations

```python
# Establish connection
await stream_manager.connect(endpoint)

# Create bidirectional stream
stream_id = await stream_manager.create_stream(
    service_id="avatar-engine",
    method="RenderFrame",
    bidirectional=True
)

# Send on stream
await stream_manager.send_stream(
    service_id="avatar-engine",
    stream_id=stream_id,
    request=video_frame
)

# Receive from stream
response = await stream_manager.receive_stream(
    service_id="avatar-engine",
    stream_id=stream_id,
    timeout=100
)

# Close stream
await stream_manager.close_stream(service_id, stream_id)
```

---

## 4. Redis Pub/Sub and Event Systems

### Redis Integration

**Session State Storage:**

- Key pattern: `session:{session_id}:state`
- TTL-based expiration for automatic cleanup
- JSON serialization for complex state

**Operations:**

```python
# Set with expiration
await redis.setex(key, ttl_seconds, json.dumps(data))

# Get data
data = json.loads(await redis.get(key))

# Check existence
exists = await redis.exists(key)

# Delete key
await redis.delete(key)
```

### Event Broadcaster

**EventMessage Structure:**

```python
class EventMessage:
    event_id: UUID
    event_type: str           # Topic name
    session_id: str           # Target session
    data: dict                # Event payload
    source_service: str       # Originating service
    source_stage: PipelineStage
    timestamp: datetime
    broadcast: bool = False   # Broadcast to all
    targets: list[str] = []   # Specific targets
```

**Pipeline Stages:**

- INPUT - Initial data ingestion
- PREPROCESSING - Data preparation
- PROCESSING - Main computation
- POSTPROCESSING - Result refinement
- OUTPUT - Final delivery

### Subscription Model

```python
# Subscribe to topic
subscription_id = broadcaster.subscribe(
    topic="session.started",
    handler=async_handler,
    filter_fn=lambda event: event.session_id == "session_123"
)

# Subscribe to all events (wildcard)
subscription_id = broadcaster.subscribe(
    topic="*",
    handler=log_all_events
)

# Publish event
delivered_count = await broadcaster.publish(
    event=EventMessage(
        event_type="session.started",
        session_id="session_123",
        data={"status": "active"}
    )
)

# Unsubscribe
broadcaster.unsubscribe(subscription_id)
```

### Event History and Replay

The EventBroadcaster maintains history for late subscribers:

```python
# Replay events from timestamp
await broadcaster.replay(
    topic="conversation.message",
    handler=catch_up_handler,
    from_timestamp=session_start_time,
    limit=100
)
```

Default history: 1000 events per topic

### WebSocket Multiplexer

Channel-based message routing for session management:

```python
# Subscribe session to channel
multiplexer.subscribe(session_id="session_123", channel_id="room_A")

# Send to specific session
await multiplexer.send(session_id="session_123", message=data)

# Broadcast to channel
await multiplexer.broadcast(channel_id="room_A", message=announcement)

# Receive from session queue
message = await multiplexer.receive(session_id="session_123", timeout=5.0)
```

---

## 5. Event Flows

### Complete Session Lifecycle

```
┌─────────────────────────────────────────────────────────────────┐
│                    SESSION LIFECYCLE                            │
└─────────────────────────────────────────────────────────────────┘

1. CREATE SESSION
   ─────────────────
   Client: POST /api/v1/sessions
       │
       ├─→ Validate request (persona_id, meeting_url)
       ├─→ Create session record in PostgreSQL
       ├─→ Initialize Redis state: session:{id}:state
       ├─→ Publish: SessionCreated event
       └─→ Return: session_id, status: PENDING

2. SUBSCRIBE TO EVENTS
   ─────────────────────
   Client: ws://host/api/v1/ws/sessions/{session_id}
       │
       ├─→ Authenticate (if token provided)
       ├─→ Register connection in ConnectionManager
       ├─→ Auto-subscribe to session events
       └─→ Ready to receive events

3. START SESSION
   ───────────────
   Client: POST /api/v1/sessions/{id}/start
       │
       ├─→ Validate session state (must be PENDING)
       ├─→ Update state: PENDING → CONNECTING
       ├─→ Broadcast: SESSION_STATE_CHANGED
       │
       ├─→ Initialize gRPC streams:
       │   ├─→ Avatar Engine stream
       │   ├─→ Voice Engine stream
       │   └─→ Perception Engine stream
       │
       ├─→ Update state: CONNECTING → ACTIVE
       ├─→ Broadcast: SESSION_STARTED
       └─→ Return: status: ACTIVE

4. JOIN MEETING (Optional)
   ────────────────────────
   Client: POST /api/v1/sessions/{id}/join-meeting
       │
       ├─→ Detect platform from URL (Zoom, Meet, Teams, Webex)
       ├─→ Broadcast: MEETING_JOINING
       │
       ├─→ gRPC to Conferencing Gateway:
       │   ├─→ Authenticate with platform
       │   ├─→ Join meeting room
       │   └─→ Start media streams
       │
       ├─→ Broadcast: MEETING_JOINED
       ├─→ Broadcast: MEETING_PARTICIPANT_JOINED
       └─→ Return: meeting_status

5. ACTIVE SESSION FLOW
   ────────────────────

   a) Input Processing
      ──────────────────
      Perception Engine → Orchestrator
          │
          ├─→ Audio frames (gRPC stream)
          ├─→ Video frames (gRPC stream)
          └─→ Emotion data (events)
               │
               ├─→ Broadcast: EMOTION_DETECTED
               └─→ Broadcast: TRANSCRIPT (partial)

   b) Turn Start
      ────────────
      Voice Engine detects speech end
          │
          ├─→ Broadcast: CONVERSATION_TURN_STARTED
          ├─→ Finalize transcript
          └─→ Broadcast: TRANSCRIPT (is_final: true)

   c) AI Processing
      ─────────────
      Orchestrator coordinates:
          │
          ├─→ Broadcast: AI_THINKING
          │
          ├─→ Query Knowledge Base (gRPC)
          │   └─→ Return: relevant documents
          │
          ├─→ Execute Tools if needed (gRPC)
          │   ├─→ Broadcast: TOOL_EXECUTING
          │   └─→ Broadcast: TOOL_COMPLETED
          │
          └─→ Query LLM (gRPC)
              └─→ Return: response text

   d) AI Response
      ────────────
      Orchestrator initiates output:
          │
          ├─→ Broadcast: AI_SPEAKING
          │
          ├─→ TTS Engine (gRPC stream):
          │   └─→ Audio chunks → Voice Engine → Meeting
          │
          ├─→ Avatar Engine (gRPC stream):
          │   ├─→ Lip sync from phonemes
          │   ├─→ Expression from emotion
          │   └─→ Video frames → Meeting
          │
          └─→ Broadcast: CONVERSATION_TURN_ENDED

   e) Continuous Monitoring
      ─────────────────────
      Every 5 seconds:
          ├─→ Broadcast: METRICS
          └─→ Health check all services

6. PAUSE SESSION
   ───────────────
   Client: Command via WebSocket or POST
       │
       ├─→ Validate state (must be ACTIVE)
       ├─→ Pause gRPC streams (don't close)
       ├─→ Update state: ACTIVE → PAUSED
       └─→ Broadcast: SESSION_PAUSED

7. RESUME SESSION
   ────────────────
   Client: Command via WebSocket or POST
       │
       ├─→ Validate state (must be PAUSED)
       ├─→ Resume gRPC streams
       ├─→ Update state: PAUSED → ACTIVE
       └─→ Broadcast: SESSION_RESUMED

8. END SESSION
   ─────────────
   Client: POST /api/v1/sessions/{id}/end
       │
       ├─→ Calculate session duration
       │
       ├─→ Close gRPC streams:
       │   ├─→ Avatar Engine
       │   ├─→ Voice Engine
       │   └─→ Perception Engine
       │
       ├─→ Leave meeting if joined
       ├─→ Broadcast: MEETING_LEFT (if applicable)
       │
       ├─→ Persist final state to PostgreSQL
       ├─→ Update state: → ENDED
       ├─→ Broadcast: SESSION_ENDED
       │
       └─→ Cleanup:
           ├─→ Close WebSocket connections
           ├─→ Delete Redis state (after TTL)
           └─→ Finalize metrics
```

### Service Registry and Discovery

The Orchestrator maintains a service registry:

```python
# Register service
registry.register(
    endpoint=ServiceEndpoint(
        service_id="avatar-engine-1",
        service_type=ServiceType.AVATAR,
        host="localhost",
        port=8001,
        protocol="grpc"
    )
)

# Select healthy service (load balanced)
service = registry.select_service(ServiceType.AVATAR)

# Update health status
registry.update_health(service_id="avatar-engine-1", healthy=True)
```

**Load Balancing:**

- Round-robin selection among healthy services
- Per-service-type load index
- Automatic failover on service failure

---

## 6. Error Handling

### HTTP Status Codes

| Code | Description         |
| ---- | ------------------- |
| 200  | Success             |
| 201  | Created             |
| 400  | Bad Request         |
| 404  | Not Found           |
| 409  | Conflict            |
| 422  | Validation Error    |
| 503  | Service Unavailable |

### WebSocket Error Message

```json
{
  "type": "error",
  "code": "SESSION_NOT_FOUND",
  "message": "Session does not exist",
  "details": {
    "session_id": "session_123"
  },
  "correlation_id": "cmd_001"
}
```

### gRPC Status Codes

| Code | Name              | Description         |
| ---- | ----------------- | ------------------- |
| 0    | OK                | Success             |
| 3    | INVALID_ARGUMENT  | Invalid request     |
| 4    | DEADLINE_EXCEEDED | Timeout             |
| 5    | NOT_FOUND         | Resource not found  |
| 14   | UNAVAILABLE       | Service unavailable |
| 16   | UNAUTHENTICATED   | Auth required       |

### Retry Strategy

**gRPC Streams:**

- Automatic reconnection with exponential backoff
- Max reconnection interval: 5 seconds
- Connection pool per service (default: 10 streams)

**HTTP Requests:**

- Client-side retry with exponential backoff
- Circuit breaker pattern for external APIs

---

## 7. Configuration

### Environment Variables

```bash
# API Gateway
SERVICE_HOST=0.0.0.0
SERVICE_PORT=8000
DATABASE_URL=postgresql://user:pass@localhost:5432/serwaa
REDIS_URL=redis://localhost:6379
CORS_ORIGINS=*
CORS_ALLOW_CREDENTIALS=true
CORS_ALLOW_METHODS=GET,POST,PUT,DELETE,PATCH,OPTIONS
CORS_ALLOW_HEADERS=*

# Orchestrator
ORCHESTRATOR_PORT=8007
GRPC_MAX_WORKERS=10
SESSION_TIMEOUT_SECONDS=3600
HEALTH_CHECK_INTERVAL=10

# gRPC Configuration
GRPC_MAX_STREAMS_PER_SERVICE=10
GRPC_RECONNECT_INTERVAL_SECONDS=5
GRPC_REQUEST_TIMEOUT_MS=30000

# Event Configuration
EVENT_HISTORY_SIZE=1000
MESSAGE_QUEUE_SIZE=1000
```

---

## 8. Message Flow Diagram

```
┌─────────────────────────────────────────────────────────────────────┐
│                         CLIENT LAYER                                │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐              │
│  │ Web Client   │  │ Mobile App   │  │ Video Client │              │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘              │
└─────────┼────────────────┼────────────────┼────────────────────────┘
          │                │                │
          │   REST/WebSocket (JSON)         │
          ▼                ▼                ▼
┌─────────────────────────────────────────────────────────────────────┐
│                        API GATEWAY (8000)                           │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐              │
│  │ REST Routers │  │  WebSocket   │  │  Connection  │              │
│  │              │  │  Handlers    │  │  Manager     │              │
│  └──────────────┘  └──────────────┘  └──────────────┘              │
└─────────────────────────────┬───────────────────────────────────────┘
                              │
                              │  Internal HTTP / WebSocket Mux
                              ▼
┌─────────────────────────────────────────────────────────────────────┐
│                      ORCHESTRATOR (8007)                            │
│  ┌────────────────────────────────────────────────────────────┐    │
│  │                  Communication Manager                      │    │
│  │  ┌────────────┐  ┌────────────┐  ┌────────────┐           │    │
│  │  │   gRPC     │  │   Event    │  │  WebSocket │           │    │
│  │  │  Streams   │  │ Broadcaster│  │ Multiplexer│           │    │
│  │  └────────────┘  └────────────┘  └────────────┘           │    │
│  └────────────────────────────────────────────────────────────┘    │
│  ┌────────────────────────────────────────────────────────────┐    │
│  │                    Service Registry                         │    │
│  │  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐          │    │
│  │  │  ASR    │ │  TTS    │ │  LLM    │ │ Avatar  │ ...      │    │
│  │  └─────────┘ └─────────┘ └─────────┘ └─────────┘          │    │
│  └────────────────────────────────────────────────────────────┘    │
└─────────────────────────────┬───────────────────────────────────────┘
                              │
         ┌────────────────────┼────────────────────┐
         │                    │                    │
    gRPC Stream          gRPC Stream          gRPC Stream
         │                    │                    │
         ▼                    ▼                    ▼
┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
│  Voice Engine   │  │  Avatar Engine  │  │ Perception Eng  │
│     (8002)      │  │     (8001)      │  │     (8004)      │
│  ┌───────────┐  │  │  ┌───────────┐  │  │  ┌───────────┐  │
│  │ Deepgram  │  │  │  │    3DGS   │  │  │  │ MediaPipe │  │
│  │ ElevenLabs│  │  │  │   FLAME   │  │  │  │  Emotion  │  │
│  └───────────┘  │  │  └───────────┘  │  │  └───────────┘  │
└─────────────────┘  └─────────────────┘  └─────────────────┘
         │                    │                    │
         └────────────────────┼────────────────────┘
                              │
                      Redis Pub/Sub
                              │
                              ▼
                    ┌─────────────────┐
                    │     Redis       │
                    │  (State/Events) │
                    └─────────────────┘
```

---

## 9. Key Implementation Files

| Component             | File Path                                                          |
| --------------------- | ------------------------------------------------------------------ |
| FastAPI App           | `services/api-gateway/src/api_gateway/app.py`                      |
| Sessions Router       | `services/api-gateway/src/api_gateway/routers/sessions.py`         |
| WebSocket Router      | `services/api-gateway/src/api_gateway/routers/websocket.py`        |
| Connection Manager    | `services/api-gateway/src/api_gateway/websocket/manager.py`        |
| WebSocket Models      | `services/api-gateway/src/api_gateway/websocket/models.py`         |
| Personas Router       | `services/api-gateway/src/api_gateway/routers/personas.py`         |
| Knowledge Router      | `services/api-gateway/src/api_gateway/routers/knowledge.py`        |
| Tools Router          | `services/api-gateway/src/api_gateway/routers/tools.py`            |
| Communication Manager | `services/orchestrator/src/orchestrator/pipeline/communication.py` |
| Pipeline Types        | `services/orchestrator/src/orchestrator/pipeline/types.py`         |
| Learning System API   | `services/learning-system/src/learning_system/main.py`             |

---

_Document generated: January 2026_ _Task: 24.1.1.2 - Analyze inter-service
communication patterns_
