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:
{
"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:
{
"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:
{
"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 functionsapi- External REST APIsmcp- Model Context Protocol serverswebhook- 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:
{
"type": "subscribe",
"session_id": "session_123",
"events": ["session.started", "session.ended", "conversation.message"]
}
Unsubscribe Message:
{
"type": "unsubscribe",
"session_id": "session_123"
}
Command Message:
{
"type": "command",
"id": "cmd_001",
"session_id": "session_123",
"command": "session.pause",
"parameters": {}
}
Ping Message:
{
"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:
{
"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:
{
"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:
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:
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#
# 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:
# 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:
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#
# 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:
# 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:
# 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:
# 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#
{
"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#
# 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