# Psyche Domain: Service Inventory

This document provides a comprehensive inventory of all microservices in the
Serwaa codebase (to be migrated to the Psyche domain within the Oshun monorepo).

## Platform Overview

Serwaa is a hyper-realistic AI virtual assistant platform for video
conferencing. It creates photorealistic digital humans capable of participating
in video conferences indistinguishably from real humans. The system combines:

- **Real-time avatar rendering** via 3D Gaussian Splatting
- **Neural voice synthesis** with sub-100ms latency
- **Conversational AI** powered by Claude
- **Computer use capabilities** via Claude Computer Use
- **Video conferencing integration** with Zoom, Teams, Meet, Webex

### Performance Targets

| Metric              | Target          |
| ------------------- | --------------- |
| Avatar rendering    | <33ms (30+ FPS) |
| Voice synthesis     | <100ms latency  |
| End-to-end response | <500ms          |
| Video quality       | 1080p @ 30 FPS  |
| Audio quality       | 48kHz, 16-bit   |

---

## Service Summary

| #   | Service              | Port         | Technology         | GPU Required      |
| --- | -------------------- | ------------ | ------------------ | ----------------- |
| 1   | API Gateway          | 8000         | Python FastAPI     | No                |
| 2   | Admin Dashboard      | 3000         | TypeScript Next.js | No                |
| 3   | Avatar Engine        | 8001         | Python FastAPI     | Yes (CUDA 12.1.1) |
| 4   | Voice Engine         | 8002         | Python FastAPI     | Yes (CUDA 12.1.1) |
| 5   | Behavior Engine      | 8003         | Python FastAPI     | No                |
| 6   | Perception Engine    | 8004         | Python FastAPI     | Yes               |
| 7   | Computer Use Engine  | 8005         | Python FastAPI     | No                |
| 8   | Conferencing Gateway | 8006         | Python FastAPI     | No                |
| 9   | Session Orchestrator | 8007         | Python FastAPI     | No                |
| 10  | Knowledge Base       | 8008         | Python FastAPI     | No                |
| 11  | Persona Service      | 8009         | Python FastAPI     | No                |
| 12  | Learning System      | 8010         | Python FastAPI     | No                |
| 13  | Tool Framework       | (integrated) | Python             | No                |
| 14  | Persona System       | (utility)    | Python             | No                |
| 15  | Security Service     | (utility)    | Python             | No                |
| 16  | Error Handling       | (utility)    | Python             | No                |
| 17  | Video Conferencing   | (utility)    | Python             | No                |
| 18  | Tavus Integration    | (utility)    | Python             | No                |
| 19  | Mock External APIs   | 4010         | Python FastAPI     | No                |

**Technology Distribution:**

- Python FastAPI services: 17
- TypeScript services: 2 (Admin Dashboard + UI package)
- Port range: 3000, 4010, 8000-8010

---

## Core Microservices

### 1. API Gateway

**Port:** 8000 **Technology:** Python FastAPI **Location:**
`serwaa/services/api-gateway/` **Docker:**
`serwaa/services/api-gateway/Dockerfile`

#### Description

REST/WebSocket API entry point for all external clients. Handles routing,
authentication, rate limiting, and session management.

#### Responsibilities

- Route management (REST endpoints + WebSocket handlers)
- Authentication and authorization (JWT/OAuth)
- Rate limiting and circuit breaking
- Session management via Redis
- Request/response serialization (JSON)
- Request validation and sanitization
- API versioning

#### Key Dependencies

```
fastapi>=0.109.0
pydantic>=2.5.0
redis>=5.0.0
sqlalchemy>=2.0.0
httpx>=0.26.0
python-jose[cryptography]>=3.3.0
passlib[bcrypt]>=1.7.4
```

#### Environment Variables

```bash
API_GATEWAY_PORT=8000
REDIS_URL=redis://localhost:6379
DATABASE_URL=postgresql://...
JWT_SECRET_KEY=...
CORS_ORIGINS=...
RATE_LIMIT_REQUESTS=100
RATE_LIMIT_WINDOW=60
```

---

### 2. Admin Dashboard

**Port:** 3000 **Technology:** TypeScript / Next.js 14 **Location:**
`serwaa/services/admin-dashboard/` **Docker:**
`serwaa/services/admin-dashboard/Dockerfile`

#### Description

Web interface for managing AI virtual assistants, personas, and system
configuration.

#### Responsibilities

- Admin UI for persona management
- Dashboard analytics and monitoring
- Configuration management
- Real-time status updates via WebSocket
- User management
- Knowledge base administration

#### Key Dependencies

```json
{
  "next": "^14.0.0",
  "react": "^18.2.0",
  "@radix-ui/react-*": "^1.0.0",
  "tailwindcss": "^3.4.0",
  "zustand": "^4.4.0",
  "@tanstack/react-query": "^5.0.0",
  "next-auth": "^5.0.0-beta"
}
```

#### Environment Variables

```bash
NEXT_PUBLIC_API_URL=http://localhost:8000
NEXTAUTH_SECRET=...
NEXTAUTH_URL=http://localhost:3000
```

---

### 3. Avatar Engine

**Port:** 8001 **Technology:** Python FastAPI (GPU-enabled) **Location:**
`serwaa/services/avatar-engine/` **Docker:**
`serwaa/services/avatar-engine/Dockerfile`

#### Description

Neural rendering engine for photorealistic avatar generation using 3D Gaussian
Splatting (3DGS). Handles real-time facial animation, expression control, and
video encoding.

#### GPU Requirements

- **Minimum:** NVIDIA RTX 3080 (10GB VRAM)
- **Recommended:** NVIDIA RTX 4090 (24GB VRAM)
- **CUDA Version:** 12.1.1
- **cuDNN Version:** 8.9.2

#### Responsibilities

- 3D Gaussian Splatting rendering (30+ FPS @ 1024x1024)
- FLAME parametric face model animation
- Expression and lip-sync control
- Real-time video encoding (H.264/H.265)
- Multi-resolution rendering (pyramid approach)
- NeRF fallback for bootstrap/legacy
- Blendshape coefficient processing
- Lighting and environment adaptation

#### Key Dependencies

```
torch>=2.1.0+cu121
torchvision>=0.16.0+cu121
opencv-python>=4.9.0
numpy>=1.26.0
pillow>=10.0.0
diff-gaussian-rasterization  # Custom CUDA extension
simple-knn  # Custom CUDA extension
```

#### Environment Variables

```bash
AVATAR_ENGINE_PORT=8001
CUDA_VISIBLE_DEVICES=0
MODEL_PATH=/models/avatar
RENDERING_RESOLUTION=1024
TARGET_FPS=30
ENABLE_MULTI_GPU=false
```

#### Performance Metrics

- Frame render time: <33ms
- GPU memory usage: ~8GB typical
- Supported expressions: 52 FLAME coefficients + 50 blendshapes

---

### 4. Voice Engine

**Port:** 8002 **Technology:** Python FastAPI (GPU-enabled) **Location:**
`serwaa/services/voice-engine/` **Docker:**
`serwaa/services/voice-engine/Dockerfile`

#### Description

TTS/STT and conversational voice engine. Handles speech-to-text transcription,
text-to-speech synthesis, and turn-taking management.

#### GPU Requirements

- **Minimum:** NVIDIA GPU with CUDA support
- **CUDA Version:** 12.1.1

#### Responsibilities

- Speech-to-text (Deepgram primary, Whisper fallback)
- Text-to-speech (ElevenLabs Flash v2.5)
- Voice activity detection (VAD)
- Speaker diarization
- Turn-taking management
- Audio streaming and buffering
- Phoneme extraction for lip sync
- Voice cloning support
- Audio format conversion (PCM, Opus, AAC)

#### Key Dependencies

```
torch>=2.1.0+cu121
deepgram-sdk>=3.0.0
elevenlabs>=1.0.0
librosa>=0.10.0
soundfile>=0.12.0
webrtcvad>=2.0.10
whisper>=20231117  # OpenAI Whisper
```

#### Environment Variables

```bash
VOICE_ENGINE_PORT=8002
DEEPGRAM_API_KEY=...
ELEVENLABS_API_KEY=...
STT_MODEL=nova-2
TTS_MODEL=eleven_flash_v2_5
SAMPLE_RATE=48000
ENABLE_VAD=true
VAD_AGGRESSIVENESS=2
```

#### Performance Metrics

- STT latency: <50ms (streaming)
- TTS latency: <100ms (first word)
- Audio buffer size: 20ms chunks

---

### 5. Behavior Engine

**Port:** 8003 **Technology:** Python FastAPI **Location:**
`serwaa/services/behavior-engine/` **Docker:**
`serwaa/services/behavior-engine/Dockerfile`

#### Description

Behavioral realism engine for generating natural expressions, gestures, and
movements. Creates human-like behaviors based on personality traits and
conversational context.

#### Responsibilities

- Eye gaze behavior system (saccades, fixations)
- Micro-expression generation
- Gesture and movement synthesis
- Personality trait-based behaviors
- FACS (Facial Action Coding System) expression control
- Natural head movement and blinking
- Breathing animation
- Idle behavior generation
- Emotional response mapping

#### Key Dependencies

```
fastapi>=0.109.0
numpy>=1.26.0
scipy>=1.11.0
pydantic>=2.5.0
```

#### Environment Variables

```bash
BEHAVIOR_ENGINE_PORT=8003
BLINK_RATE_PER_MINUTE=15
SACCADE_FREQUENCY=3.0
IDLE_ANIMATION_ENABLED=true
```

#### Behavior Parameters

| Behavior         | Range       | Default |
| ---------------- | ----------- | ------- |
| Blink rate       | 10-25/min   | 15/min  |
| Saccade freq     | 2-4 Hz      | 3 Hz    |
| Head movement    | ±15 degrees | ±10°    |
| Micro-expression | 50-500ms    | 200ms   |

---

### 6. Perception Engine

**Port:** 8004 **Technology:** Python FastAPI (GPU-enabled) **Location:**
`serwaa/services/perception-engine/` **Docker:**
`serwaa/services/perception-engine/Dockerfile`

#### Description

Multi-modal perception for understanding user input. Processes video, audio, and
text to extract emotions, intent, and context.

#### GPU Requirements

- NVIDIA GPU with CUDA support (for real-time inference)

#### Responsibilities

- Emotion detection (face and voice)
- User intent classification
- Screen content understanding (OCR)
- Multi-modal context fusion
- Face detection and tracking
- Sentiment analysis
- Visual scene comprehension
- Engagement level detection
- Attention tracking

#### Key Dependencies

```
torch>=2.1.0+cu121
opencv-python>=4.9.0
face_recognition>=1.3.0
mediapipe>=0.10.0
transformers>=4.36.0
scikit-learn>=1.3.0
pytesseract>=0.3.10
```

#### Environment Variables

```bash
PERCEPTION_ENGINE_PORT=8004
EMOTION_MODEL=fer2013
FACE_DETECTION_MODEL=mediapipe
OCR_ENABLED=true
MULTIMODAL_FUSION=true
```

---

### 7. Computer Use Engine

**Port:** 8005 **Technology:** Python FastAPI **Location:**
`serwaa/services/computer-use/` **Docker:**
`serwaa/services/computer-use/Dockerfile`

#### Description

Claude Computer Use agent for desktop automation. Enables the AI assistant to
browse the web, use applications, and perform tasks on the user's behalf.

#### Security Model

- Sandboxed Docker container execution
- Ephemeral storage (cleared after session)
- Network allowlist for approved domains
- Action auditing and logging
- User confirmation for sensitive actions

#### Responsibilities

- Sandboxed desktop environment management
- Browser automation (Chrome via Selenium)
- Mouse and keyboard action execution
- Screen capture and OCR
- Computer use reasoning via Claude
- Action verification and retry logic
- Session isolation
- Action history tracking

#### Key Dependencies

```
anthropic>=0.18.0
selenium>=4.16.0
pyautogui>=0.9.54
pillow>=10.0.0
docker>=7.0.0
```

#### Environment Variables

```bash
COMPUTER_USE_PORT=8005
ANTHROPIC_API_KEY=...
SANDBOX_IMAGE=serwaa/sandbox:latest
BROWSER_HEADLESS=true
SCREENSHOT_INTERVAL_MS=1000
ACTION_TIMEOUT_SECONDS=30
ALLOWED_DOMAINS=google.com,github.com,...
```

---

### 8. Conferencing Gateway

**Port:** 8006 **Technology:** Python FastAPI **Location:**
`serwaa/services/conferencing/` **Docker:**
`serwaa/services/conferencing/Dockerfile`

#### Description

Video conferencing platform integration hub. Provides unified interface for
joining meetings across multiple platforms.

#### Platform Integrations

| Platform        | Integration Type | Status     |
| --------------- | ---------------- | ---------- |
| Zoom            | SDK + OAuth      | Production |
| Google Meet     | SDK              | Production |
| Microsoft Teams | SDK              | Production |
| Webex           | WebRTC           | Beta       |

#### Responsibilities

- Video conferencing platform adapters
- Media stream management (audio/video)
- Virtual camera integration (v4l2loopback on Linux)
- Virtual microphone integration (PulseAudio)
- Meeting state synchronization
- Participant management
- Screen share handling
- Recording integration (optional)
- Platform-specific feature adaptation

#### Key Dependencies

```
fastapi>=0.109.0
zoomus>=0.1.15  # Zoom SDK
google-auth>=2.25.0
msal>=1.26.0  # Microsoft Teams
aiortc>=1.6.0  # WebRTC
av>=11.0.0  # PyAV for media
```

#### Environment Variables

```bash
CONFERENCING_PORT=8006
ZOOM_CLIENT_ID=...
ZOOM_CLIENT_SECRET=...
GOOGLE_CREDENTIALS_PATH=...
AZURE_CLIENT_ID=...
AZURE_CLIENT_SECRET=...
WEBEX_ACCESS_TOKEN=...
VIRTUAL_CAMERA_DEVICE=/dev/video10
```

---

### 9. Session Orchestrator

**Port:** 8007 **Technology:** Python FastAPI **Location:**
`serwaa/services/orchestrator/` **Docker:**
`serwaa/services/orchestrator/Dockerfile`

#### Description

Central session coordination and state management. Acts as the hub for all
service communication during an active session.

#### Communication Pattern

Hub-and-spoke architecture with gRPC streaming to core engines:

```
                    ┌─────────────────┐
                    │  Orchestrator   │
                    │    (Port 8007)  │
                    └────────┬────────┘
                             │
         ┌───────────────────┼───────────────────┐
         │                   │                   │
    gRPC Stream         gRPC Stream         gRPC Stream
         │                   │                   │
         ▼                   ▼                   ▼
  ┌──────────────┐   ┌──────────────┐   ┌──────────────┐
  │Avatar Engine │   │ Voice Engine │   │  Perception  │
  │  (8001)      │   │   (8002)     │   │   (8004)     │
  └──────────────┘   └──────────────┘   └──────────────┘
```

#### Responsibilities

- Session lifecycle management (create, join, leave, end)
- Service registry and health checking
- gRPC stream management (bidirectional streams)
- Resource allocation and load balancing
- Real-time processing pipeline coordination
- State synchronization across services
- Error handling and fallback management
- Message routing and queue management
- Session persistence and recovery

#### Key Dependencies

```
fastapi>=0.109.0
grpcio>=1.60.0
grpcio-tools>=1.60.0
redis>=5.0.0
sqlalchemy>=2.0.0
```

#### Environment Variables

```bash
ORCHESTRATOR_PORT=8007
REDIS_URL=redis://localhost:6379
DATABASE_URL=postgresql://...
GRPC_MAX_WORKERS=10
SESSION_TIMEOUT_SECONDS=3600
HEALTH_CHECK_INTERVAL=10
```

---

### 10. Knowledge Base Service

**Port:** 8008 **Technology:** Python FastAPI **Location:**
`serwaa/services/knowledge-base/` **Docker:**
`serwaa/services/knowledge-base/Dockerfile`

#### Description

RAG (Retrieval-Augmented Generation) system with vector search. Ingests
documents and provides semantic search for contextual responses.

#### Responsibilities

- Document ingestion (PDF, DOCX, HTML, JSON, Markdown)
- Text chunking (semantic + hierarchical)
- Embedding generation (Voyage AI primary, OpenAI fallback)
- Vector storage in Qdrant
- Semantic similarity search
- Hybrid search (vector + keyword BM25)
- Document retrieval and ranking (Cohere reranking)
- RAG context generation for LLM
- Metadata management
- Source citation tracking

#### Key Dependencies

```
fastapi>=0.109.0
qdrant-client>=1.7.0
sentence-transformers>=2.2.0
voyageai>=0.2.0
openai>=1.6.0
cohere>=4.37.0
pypdf>=3.17.0
python-docx>=1.0.0
beautifulsoup4>=4.12.0
```

#### Environment Variables

```bash
KNOWLEDGE_BASE_PORT=8008
QDRANT_URL=http://localhost:6333
QDRANT_COLLECTION=knowledge
VOYAGE_API_KEY=...
OPENAI_API_KEY=...
COHERE_API_KEY=...
EMBEDDING_MODEL=voyage-2
CHUNK_SIZE=512
CHUNK_OVERLAP=50
```

#### Vector Configuration

| Parameter            | Value           |
| -------------------- | --------------- |
| Embedding dimensions | 1024 (Voyage-2) |
| Distance metric      | Cosine          |
| HNSW ef_construct    | 128             |
| HNSW m               | 16              |

---

### 11. Persona Service

**Port:** 8009 **Technology:** Python FastAPI **Location:**
`serwaa/services/persona-service/` **Docker:**
`serwaa/services/persona-service/Dockerfile`

#### Description

Avatar personality and identity configuration. Manages persona definitions,
behavioral traits, and enterprise templates.

#### Responsibilities

- Avatar identity management
- Personality trait settings (Big Five model)
- Behavioral customization
- Enterprise persona templates
- Persona versioning and rollback
- Persona analytics
- Voice profile association
- Avatar appearance settings
- Default response styles

#### Key Dependencies

```
fastapi>=0.109.0
pydantic>=2.5.0
sqlalchemy>=2.0.0
```

#### Persona Schema

```python
class Persona:
    id: UUID
    name: str
    description: str
    avatar_model_id: str
    voice_id: str
    personality: PersonalityTraits
    behavioral_settings: BehaviorSettings
    knowledge_base_ids: list[UUID]
    created_at: datetime
    updated_at: datetime
```

---

### 12. Learning System

**Port:** 8010 **Technology:** Python FastAPI **Location:**
`serwaa/services/learning-system/` **Docker:**
`serwaa/services/learning-system/Dockerfile`

#### Description

Persistent memory system (MemGPT/Letta-style) for continuous learning. Enables
cross-session memory retention and user preference learning.

#### Memory Hierarchy

| Tier           | Capacity    | Access Time | Persistence |
| -------------- | ----------- | ----------- | ----------- |
| IN_CONTEXT     | ~8K tokens  | Immediate   | Session     |
| WORKING        | ~32K tokens | <10ms       | Session     |
| OUT_OF_CONTEXT | ~1M tokens  | <100ms      | Persistent  |
| ARCHIVAL       | Unlimited   | <500ms      | Persistent  |

#### Responsibilities

- Four-tier memory hierarchy management
- Self-editing memory tools:
  - `core_memory_append` - Add to working memory
  - `core_memory_replace` - Update working memory
  - `archival_memory_insert` - Store long-term
  - `archival_memory_search` - Retrieve from archive
- Cross-session persistence with encryption
- Memory decay and consolidation
- Semantic memory search
- User preference learning
- Skill acquisition and retention
- Memory paging between tiers

#### Key Dependencies

```
fastapi>=0.109.0
qdrant-client>=1.7.0
sentence-transformers>=2.2.0
cryptography>=41.0.0
apscheduler>=3.10.0
```

#### Environment Variables

```bash
LEARNING_SYSTEM_PORT=8010
QDRANT_URL=http://localhost:6333
MEMORY_COLLECTION=memories
ENCRYPTION_KEY=...
MEMORY_DECAY_HOURS=72
CONSOLIDATION_INTERVAL=3600
```

---

## Utility Services

### 13. Tool Framework

**Technology:** Python (integrated module) **Location:**
`serwaa/services/tool-framework/`

#### Description

External tool integration and Model Context Protocol (MCP) support. Enables the
AI to use external tools and integrate with enterprise systems.

#### Responsibilities

- Tool registration and discovery
- MCP server integration
- Enterprise system connectors (CRM, ERP, Calendar)
- Tool execution orchestration
- Action result processing
- Custom tool support
- Tool schema management (JSON Schema)
- Tool rate limiting

#### Supported Tool Categories

- **Calendar:** Google Calendar, Outlook, Calendly
- **CRM:** Salesforce, HubSpot, Pipedrive
- **Communication:** Slack, Teams, Email
- **Productivity:** Notion, Asana, Jira
- **Custom:** MCP-compatible tools

---

### 14-18. Supporting Services

| Service            | Location                              | Purpose                     |
| ------------------ | ------------------------------------- | --------------------------- |
| Persona System     | `serwaa/services/persona-system/`     | Core persona data models    |
| Security Service   | `serwaa/services/security/`           | Auth/encryption utilities   |
| Error Handling     | `serwaa/services/error_handling/`     | Centralized error handling  |
| Video Conferencing | `serwaa/services/video-conferencing/` | Video codec utilities       |
| Tavus Integration  | `serwaa/services/tavus-integration/`  | Third-party avatar fallback |

---

### 19. Mock External APIs

**Port:** 4010 **Technology:** Python FastAPI **Location:**
`serwaa/services/mock-external-apis/`

#### Description

Local mock services for development testing. Simulates external API responses
for offline development.

#### Mocked APIs

- Deepgram STT API
- ElevenLabs TTS API
- OpenAI API
- Anthropic Claude API
- Voyage AI Embeddings API
- Zoom SDK endpoints
- Google Meet SDK endpoints

#### Environment Variables

```bash
USE_MOCK_EXTERNAL_APIS=true
MOCK_API_PORT=4010
MOCK_LATENCY_MS=50
```

---

## Shared Packages

Located at `serwaa/packages/`:

| Package                 | Technology       | Purpose                             |
| ----------------------- | ---------------- | ----------------------------------- |
| `@serwaa/common`        | Python           | Shared utilities, types, config     |
| `@serwaa/ml-utils`      | Python           | ML inference helpers, preprocessing |
| `@serwaa/proto`         | Protocol Buffers | gRPC service definitions            |
| `@serwaa/security`      | Python           | Encryption, JWT, validation         |
| `@serwaa/testing`       | TypeScript       | Test fixtures, mocks                |
| `@serwaa/tsconfig`      | TypeScript       | Shared TS configuration             |
| `@serwaa/eslint-config` | JavaScript       | Shared ESLint configuration         |
| `@serwaa/ui`            | TypeScript/React | Reusable UI components              |

---

## Infrastructure Dependencies

### Required Services

| Service    | Type           | Port      | Purpose                    |
| ---------- | -------------- | --------- | -------------------------- |
| PostgreSQL | Database       | 5432      | Primary data (pgvector)    |
| Redis      | Cache/Queue    | 6379      | Sessions, Streams, Pub/Sub |
| Qdrant     | Vector DB      | 6333/6334 | Semantic search            |
| MinIO      | Object Storage | 9000/9001 | Model/media storage        |

### Optional Services

| Service       | Type          | Port      | Purpose             |
| ------------- | ------------- | --------- | ------------------- |
| Prometheus    | Metrics       | 9090      | Metrics collection  |
| Grafana       | Visualization | 3001      | Dashboards          |
| Jaeger        | Tracing       | 16686     | Distributed tracing |
| Loki          | Logs          | 3100      | Log aggregation     |
| Elasticsearch | Search        | 9200      | Full-text search    |
| Neo4j         | Graph DB      | 7687      | Knowledge graph     |
| Kafka         | Streaming     | 9092      | Event streaming     |
| NVIDIA Triton | Inference     | 8000/8001 | Model serving       |

---

## Communication Architecture

### Protocol Matrix

| Protocol      | Latency | Use Case                     |
| ------------- | ------- | ---------------------------- |
| gRPC Streams  | <10ms   | Real-time service-to-service |
| REST/HTTP     | <50ms   | API Gateway, CRUD operations |
| WebSocket     | <20ms   | Real-time client updates     |
| Redis Streams | <5ms    | Async event processing       |
| Redis Pub/Sub | <5ms    | Broadcast notifications      |

### Service Connection Diagram

```
External Clients (Zoom/Teams/Meet/Webex)
                    │
                    ▼
            ┌───────────────┐
            │  API Gateway  │ ◄──── Admin Dashboard
            │   (8000)      │
            └───────┬───────┘
                    │
                    ▼
            ┌───────────────┐
            │  Orchestrator │
            │   (8007)      │
            └───────┬───────┘
                    │
    ┌───────────────┼───────────────┬───────────────┐
    │               │               │               │
    ▼               ▼               ▼               ▼
┌─────────┐   ┌─────────┐   ┌─────────┐   ┌─────────┐
│ Avatar  │   │  Voice  │   │Perception│  │Computer │
│ Engine  │   │ Engine  │   │ Engine  │   │  Use    │
│ (8001)  │   │ (8002)  │   │ (8004)  │   │ (8005)  │
└─────────┘   └─────────┘   └─────────┘   └─────────┘
    │               │               │
    └───────────────┼───────────────┘
                    │
        ┌───────────┴───────────┐
        ▼                       ▼
┌───────────────┐       ┌───────────────┐
│   Behavior    │       │  Conferencing │
│   Engine      │       │   Gateway     │
│   (8003)      │       │   (8006)      │
└───────────────┘       └───────────────┘
        │
┌───────┴───────────────────────────────┐
▼               ▼               ▼
┌─────────┐ ┌─────────┐ ┌─────────┐
│Knowledge│ │ Persona │ │Learning │
│  Base   │ │ Service │ │ System  │
│ (8008)  │ │ (8009)  │ │ (8010)  │
└─────────┘ └─────────┘ └─────────┘
```

---

## GPU Requirements Summary

| Service           | Min GPU  | Rec GPU  | VRAM  | CUDA   |
| ----------------- | -------- | -------- | ----- | ------ |
| Avatar Engine     | RTX 3080 | RTX 4090 | 10GB+ | 12.1.1 |
| Voice Engine      | Any CUDA | RTX 3070 | 8GB+  | 12.1.1 |
| Perception Engine | Any CUDA | RTX 3070 | 8GB+  | 12.1.1 |

**Total GPU recommendation for production:**

- 1x NVIDIA RTX 4090 (24GB) for Avatar Engine
- 1x NVIDIA RTX 3080 (10GB) for Voice + Perception

---

## Development Quick Start

### Start Infrastructure

```bash
cd /home/ubuntu/oshun/serwaa

# Start core infrastructure
docker compose -f infrastructure/docker/docker-compose.dev.yml up -d

# Start services (CPU-only mode)
docker compose -f infrastructure/docker/docker-compose.services.yml up -d

# Start GPU services (requires NVIDIA Docker)
docker compose -f infrastructure/docker/docker-compose.gpu.yml up -d
```

### Service URLs (localhost)

| Service           | URL                   |
| ----------------- | --------------------- |
| API Gateway       | http://localhost:8000 |
| Admin Dashboard   | http://localhost:3000 |
| Avatar Engine     | http://localhost:8001 |
| Voice Engine      | http://localhost:8002 |
| Behavior Engine   | http://localhost:8003 |
| Perception Engine | http://localhost:8004 |
| Computer Use      | http://localhost:8005 |
| Conferencing      | http://localhost:8006 |
| Orchestrator      | http://localhost:8007 |
| Knowledge Base    | http://localhost:8008 |
| Persona Service   | http://localhost:8009 |
| Learning System   | http://localhost:8010 |
| Mock APIs         | http://localhost:4010 |

---

## Migration Path to Psyche Domain

The Serwaa codebase will be migrated to the Oshun monorepo under the Psyche
domain:

| Source                               | Destination                      |
| ------------------------------------ | -------------------------------- |
| `serwaa/services/api-gateway/`       | `apps/psyche/api-gateway/`       |
| `serwaa/services/admin-dashboard/`   | `apps/psyche/admin-dashboard/`   |
| `serwaa/services/avatar-engine/`     | `libs/psyche/avatar-engine/`     |
| `serwaa/services/voice-engine/`      | `libs/psyche/voice-engine/`      |
| `serwaa/services/behavior-engine/`   | `libs/psyche/behavior-engine/`   |
| `serwaa/services/perception-engine/` | `libs/psyche/perception-engine/` |
| `serwaa/services/computer-use/`      | `libs/psyche/computer-use/`      |
| `serwaa/services/conferencing/`      | `libs/psyche/conferencing/`      |
| `serwaa/services/orchestrator/`      | `apps/psyche/orchestrator/`      |
| `serwaa/services/knowledge-base/`    | `libs/psyche/knowledge-base/`    |
| `serwaa/services/persona-service/`   | `libs/psyche/persona-service/`   |
| `serwaa/services/learning-system/`   | `libs/psyche/learning-system/`   |
| `serwaa/packages/common/`            | `libs/psyche/common/`            |
| `serwaa/packages/ml-utils/`          | `libs/psyche/ml-utils/`          |
| `serwaa/packages/proto/`             | `libs/psyche/proto/`             |
| `serwaa/packages/security/`          | `libs/psyche/security/`          |

---

_Document generated: January 2026_ _Task: 24.1.1.1 - Document all Serwaa
microservices and responsibilities_
