Eve library

Psyche Domain: Communication Architecture

Guide

Revision 1

On this page

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:

text
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#

text
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.

text
┌────────────────────────────────────────────────────────┐
│                    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#

text
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#

text
┌─────────────────────────────────────────────────────────────────┐
│                    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#

text
┌─────────────────────────────────────────────────────────────────────┐
│                         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