Migration Status: Eve → Aphrodite (Oshun Domain)
This document provides a comprehensive analysis of inter-service communication patterns, protocols, and data flows in the Eve platform for migration planning.
Table of Contents#
- Communication Overview
- REST APIs
- WebSocket Communication
- Message Queues (Kafka)
- Event Bus Patterns
- gRPC Services
- Redis Pub/Sub & Caching
- Service-to-Service Integration
- Data Flow Diagrams
- Configuration Reference
Communication Overview#
The Eve platform uses a multi-protocol communication architecture optimized for different use cases:
| Protocol | Use Case | Services |
|---|---|---|
| REST | Client APIs, service endpoints | User, Content, Analytics, Recommendation |
| WebSocket | Real-time bidirectional | Chat, Notifications, Stream events |
| Kafka | Event streaming, fan-out | Chat, Stream, Analytics |
| gRPC | Service-to-service RPC | Stream Service |
| Redis Pub/Sub | Socket.io horizontal scaling | Chat, Notifications |
| EventEmitter | In-process events | Analytics, Goals, Subscriptions |
Architecture Diagram#
CLIENTS
┌─────────────────────────────────────────────────────────┐
│ Web │ Mobile │ VR │ OBS │ IoT Devices │
└────────────────────────┬────────────────────────────────┘
│
┌────────┴────────┐
│ EDGE LAYER │
│ (CDN / WAF) │
└────────┬────────┘
│
┌───────────────────┼───────────────────┐
▼ ▼ ▼
┌─────────┐ ┌─────────┐ ┌─────────────┐
│ API │ │ Media │ │ WebSocket │
│ Gateway │ │ Gateway │ │ Gateway │
│ (REST) │ │(WebRTC) │ │ (Socket.io) │
└────┬────┘ └────┬────┘ └──────┬──────┘
│ │ │
└──────────────────┼────────────────────┘
│
┌────────┴────────┐
│ SERVICE MESH │
└────────┬────────┘
│
┌───────────────────────┼───────────────────────────┐
│ │ │
▼ ▼ ▼
┌────────────┐ ┌────────────┐ ┌────────────┐
│ User │ │ Stream │ │ Chat │
│ Service │◄────►│ Service │◄────────────►│ Service │
│ (REST) │gRPC │ (gRPC) │ Kafka │ (Socket.io)│
└─────┬──────┘ └─────┬──────┘ └─────┬──────┘
│ │ │
│ ┌──────────────┼──────────────┐ │
│ │ │ │ │
▼ ▼ ▼ ▼ ▼
┌────────────┐ ┌────────────┐ ┌────────────────┐
│ Content │ │ Analytics │ │ Notification │
│ Service │ │ Service │ │ Service │
│ (REST) │ │ (REST) │ │ (Socket.io) │
└─────┬──────┘ └─────┬──────┘ └───────┬────────┘
│ │ │
└───────────────────┼─────────────────────┘
│
┌────────────────┼────────────────┐
│ │ │
▼ ▼ ▼
┌─────────┐ ┌───────────┐ ┌─────────┐
│PostgreSQL│ │ClickHouse│ │ MongoDB │
│ (Primary)│ │(Analytics)│ │ (Chat) │
└─────────┘ └───────────┘ └─────────┘
│ │ │
└────────────────┼────────────────┘
│
┌────────────────┼────────────────┐
│ │ │
▼ ▼ ▼
┌─────────┐ ┌─────────┐ ┌─────────┐
│ Redis │ │ Kafka │ │ S3 │
│ (Cache) │ │ (Events)│ │ (Media) │
└─────────┘ └─────────┘ └─────────┘
REST APIs#
Service Endpoints#
User Service (Port 3000)#
| Route | Method | Description |
|---|---|---|
/healthz |
GET | Health check |
/register |
POST | User registration |
/login |
POST | Authentication |
/refresh-token |
POST | Token refresh |
/profile |
GET/PUT | User profile |
/creator |
GET/PUT | Creator profile |
/settings |
GET/PUT | User settings |
/follow |
POST/DELETE | Social graph |
/fan-club |
GET/POST | Fan clubs |
Content Service (Port 7001)#
| Route | Method | Description |
|---|---|---|
/healthz |
GET | Health check |
/content-store/* |
CRUD | Content management |
/media/upload |
POST | Media upload |
/photosets/* |
CRUD | Photo set management |
/vod/* |
CRUD | VOD management |
Analytics Service (Port 7000)#
| Route | Method | Description |
|---|---|---|
/healthz |
GET | Health check |
/api/ingestion/* |
POST | Event ingestion |
/api/creator-dashboard/* |
GET | Creator metrics |
Recommendation Service (Port 7004)#
| Route | Method | Description |
|---|---|---|
/healthz |
GET | Health check |
/api/personalized-home |
GET | Personalized feed |
/api/for-you |
GET | For you recommendations |
/api/similar-creators |
GET | Similar creators |
/api/because-you-watched |
GET | Contextual recs |
/api/trending |
GET | Trending content |
HTTP Client Patterns#
// Location: eve/apps/web/lib/api-client.ts
interface ApiClientConfig {
baseUrl: string;
authTokenProvider?: () => Promise<string | null>;
}
class ApiClient {
async request<T>(endpoint: string, options?: RequestInit): Promise<T>;
async get<T>(endpoint: string, options?: RequestInit): Promise<T>;
async post<T>(
endpoint: string,
body: unknown,
options?: RequestInit
): Promise<T>;
async put<T>(
endpoint: string,
body: unknown,
options?: RequestInit
): Promise<T>;
async delete<T>(endpoint: string, options?: RequestInit): Promise<T>;
}
WebSocket Communication#
Socket.io Architecture#
The Eve platform uses Socket.io with Redis adapter for horizontal scaling across multiple server instances.
Configuration#
// Location: eve/apps/chat-service/src/redis.ts
import { createAdapter } from '@socket.io/redis-adapter';
import { createClient } from 'redis';
const pubClient = createClient({ url: process.env.REDIS_URL });
const subClient = pubClient.duplicate();
io.adapter(createAdapter(pubClient, subClient));
Chat Service Events#
Location: eve/apps/chat-service/src/socket/
Connection Management#
| Event (Client) | Event (Server) | Description |
|---|---|---|
connection |
- | User connects with auth |
disconnect |
- | User disconnects |
Room Management#
| Event (Client) | Event (Server) | Description |
|---|---|---|
room:join |
room:joined |
Join chat room |
room:leave |
room:left |
Leave chat room |
Chat Messages#
| Event (Client) | Event (Server) | Description |
|---|---|---|
message:send |
message:sent |
Send message |
| - | message:broadcast |
Broadcast to room |
Message Payload:
interface ChatMessagePayload {
roomId: string;
message: string;
userId: string;
socketId: string;
timestamp: Date;
type: 'text' | 'tip' | 'system';
}
Message Features:
- Rate limiting
- Slow mode support
- Subscriber/follower access control
- Message persistence (MongoDB)
Typing Indicators#
| Event (Client) | Event (Server) | Description |
|---|---|---|
typing:start |
typing:indicator |
Start typing |
typing:stop |
typing:indicator |
Stop typing |
Message Recovery#
| Event (Client) | Event (Server) | Description |
|---|---|---|
recovery:request |
recovery:messages |
Recover missed messages |
Stream Integration#
| Event (Client) | Event (Server) | Description |
|---|---|---|
stream:join |
- | Join stream chat |
stream:leave |
- | Leave stream chat |
Emoji Reactions#
| Event (Client) | Event (Server) | Description |
|---|---|---|
emoji:send |
emoji:broadcast |
Send emoji reaction |
Commands#
| Event (Client) | Event (Server) | Description |
|---|---|---|
command:execute |
command:response |
Execute command |
Direct Messaging Events#
Location: eve/apps/chat-service/src/dm-handlers.ts
| Event (Client) | Event (Server) | Description |
|---|---|---|
dm:create-conversation |
dm:conversation-created |
Create DM conversation |
dm:send |
dm:message-sent |
Send DM |
| - | dm:message-received |
DM received (target user) |
dm:get-messages |
dm:messages |
Get message history |
dm:get-conversations |
dm:conversations |
Get conversations list |
dm:mark-read |
dm:marked-read |
Mark as read |
dm:get-unread |
dm:unread |
Get unread count |
dm:delete-message |
dm:message-deleted |
Delete message |
dm:block |
dm:conversation-blocked |
Block user |
dm:unblock |
dm:conversation-unblocked |
Unblock user |
dm:send-mass |
dm:mass-dm-created |
Mass DM (async) |
dm:get-mass-dm-status |
dm:mass-dm-status |
Mass DM status |
Cross-Socket Broadcasting:
// Broadcast to target user across all their connected sockets
io.to(`user:${otherUserId}`).emit('dm:message-received', message);
Notification Service Events#
Location: eve/apps/notification-service/src/notification-handlers.ts
Room Pattern: user:${userId}:notifications
| Event (Client) | Event (Server) | Description |
|---|---|---|
notification:get |
notification:list |
Get notifications |
notification:get-unread |
notification:unread-list |
Get unread |
notification:get-stats |
notification:stats |
Get stats |
notification:mark-read |
notification:marked-read |
Mark as read |
notification:mark-all-read |
notification:all-marked-read |
Mark all read |
notification:dismiss |
notification:dismissed |
Dismiss notification |
notification:delete |
notification:deleted |
Delete notification |
notification:get-preferences |
notification:preferences |
Get preferences |
notification:update-preferences |
notification:preferences-updated |
Update preferences |
notification:subscribe |
- | Subscribe to channel |
notification:unsubscribe |
- | Unsubscribe |
Server-side Broadcasting:
// Push notification to user
function pushNotificationToUser(
io: Server,
userId: string,
notification: Notification
): void;
// Push stats to user
function pushStatsToUser(
io: Server,
userId: string,
stats: NotificationStats
): void;
// Broadcast read status
function broadcastNotificationRead(
io: Server,
userId: string,
notificationId: string
): void;
Stream Service Events#
Location: eve/apps/stream-service/src/public-show-integration.ts
Goal Events#
| Event | Direction | Description |
|---|---|---|
goal:completed |
Server → Client | Goal completed |
goal:expired |
Server → Client | Goal expired |
goal:progress |
Server → Client | Goal progress update |
Event Flow:
Goal Service (EventEmitter)
│
▼
Public Show Integration
│
▼
Socket.io broadcast to stream:${streamId}
│
▼
Connected viewers receive goal updates
Message Queues (Kafka)#
Kafka Configuration#
Chat Service#
Location: eve/apps/chat-service/src/kafka.ts
const kafka = new Kafka({
clientId: 'chat-service',
brokers: process.env.KAFKA_BROKERS?.split(',') ?? ['localhost:9092'],
});
const producer = kafka.producer();
const consumer = kafka.consumer({ groupId: 'chat-service-group' });
Stream Service#
Location: eve/apps/stream-service/src/kafka.ts
const kafka = new Kafka({
clientId: 'stream-service',
brokers: process.env.KAFKA_BROKERS?.split(',') ?? ['localhost:9092'],
});
const producer = kafka.producer();
Topics & Events#
| Topic | Producer | Consumer | Description |
|---|---|---|---|
chat.messages |
Chat Service | Analytics, Moderation | Chat message events |
stream.events |
Stream Service | Analytics, Notification | Stream lifecycle events |
payment.events |
Payment Service | Analytics, Notification | Payment/tip events |
user.events |
User Service | Analytics | User activity events |
Event Envelope Pattern#
interface KafkaEvent<T> {
id: string;
type: string;
timestamp: Date;
source: string;
payload: T;
}
Event Bus Patterns#
EventEmitter Integration#
The Eve platform uses Node.js EventEmitter for in-process event distribution.
Analytics Pipeline#
Location: eve/apps/analytics-service/src/index.ts
const eventBus = new EventEmitter();
const pipeline = createAnalyticsPipeline(clickhouse, eventBus);
// Event subscription
eventBus.on('analytics.events.flushed', (count: number) => {
logger.info(`Flushed ${count} events to ClickHouse`);
});
Stream Goal System#
Location: eve/apps/stream-service/src/public-show-integration.ts
// Goal service emits events
goalService.on('goal.completed', async (goal: Goal) => {
// Broadcast to stream room
io.to(`stream:${goal.streamId}`).emit('goal:completed', goal);
// Trigger toy vibration
await vibrationHandler.onGoalComplete(goal);
});
goalService.on('goal.progress', (goal: Goal, progress: number) => {
io.to(`stream:${goal.streamId}`).emit('goal:progress', { goal, progress });
});
goalService.on('goal.expired', (goal: Goal) => {
io.to(`stream:${goal.streamId}`).emit('goal:expired', goal);
});
Subscription Events#
Location: eve/apps/user-service/src/subscription/service.ts
class SubscriptionService {
constructor(
private readonly eventBus: EventEmitter
// ...other deps
) {}
async createTier(tier: TierData): Promise<Tier> {
const created = await this.repository.createTier(tier);
this.eventBus.emit('subscription.tier.created', created);
return created;
}
}
gRPC Services#
Stream Service gRPC Server#
Location: eve/apps/stream-service/src/grpc/server.ts
import { Server, ServerCredentials } from '@grpc/grpc-js';
const host = process.env.STREAM_SERVICE_HOST ?? '0.0.0.0';
const port = process.env.STREAM_SERVICE_PORT ?? 50051;
const server = new Server();
server.bindAsync(
`${host}:${port}`,
ServerCredentials.createInsecure(),
(err, port) => {
if (err) throw err;
server.start();
}
);
Protocol Buffer Definitions#
Location: eve/packages/proto/proto/
Stream Service (stream.proto)#
syntax = "proto3";
package eve.stream.v1;
import "google/protobuf/timestamp.proto";
enum StreamStatus {
STREAM_STATUS_UNSPECIFIED = 0;
STREAM_STATUS_SCHEDULED = 1;
STREAM_STATUS_LIVE = 2;
STREAM_STATUS_COMPLETED = 3;
STREAM_STATUS_CANCELLED = 4;
}
message Stream {
string id = 1;
string creator_id = 2;
string title = 3;
string description = 4;
StreamStatus status = 5;
google.protobuf.Timestamp scheduled_start = 6;
google.protobuf.Timestamp started_at = 7;
google.protobuf.Timestamp ended_at = 8;
string thumbnail_url = 9;
}
User Service (user.proto)#
syntax = "proto3";
package eve.user.v1;
import "google/protobuf/timestamp.proto";
message User {
string id = 1;
string email = 2;
string username = 3;
string display_name = 4;
string avatar_url = 5;
bool verified = 6;
google.protobuf.Timestamp created_at = 7;
}
Chat Service (chat.proto)#
syntax = "proto3";
package eve.chat.v1;
import "google/protobuf/timestamp.proto";
enum MessageType {
MESSAGE_TYPE_TEXT = 0;
MESSAGE_TYPE_SYSTEM = 1;
MESSAGE_TYPE_TIP = 2;
}
message ChatMessage {
string id = 1;
string room_id = 2;
string sender_id = 3;
string content = 4;
MessageType type = 5;
google.protobuf.Timestamp created_at = 6;
}
Events (events.proto)#
syntax = "proto3";
package eve.events.v1;
import "google/protobuf/timestamp.proto";
message StreamStarted {
string stream_id = 1;
google.protobuf.Timestamp started_at = 2;
}
message PaymentReceived {
string payment_id = 1;
string user_id = 2;
double amount = 3;
google.protobuf.Timestamp received_at = 4;
}
message ChatMessageCreated {
string message_id = 1;
string room_id = 2;
string sender_id = 3;
google.protobuf.Timestamp created_at = 4;
}
message EventEnvelope {
string id = 1;
string type = 2;
google.protobuf.Timestamp occurred_at = 3;
oneof payload {
StreamStarted stream_started = 10;
PaymentReceived payment_received = 11;
ChatMessageCreated chat_message_created = 12;
}
}
Redis Pub/Sub & Caching#
Socket.io Redis Adapter#
Location: eve/apps/chat-service/src/redis.ts
import { createAdapter } from '@socket.io/redis-adapter';
import { createClient } from 'redis';
export async function setupRedisAdapter(io: Server): Promise<void> {
const url = process.env.REDIS_URL ?? 'redis://localhost:6379';
const pubClient = createClient({ url });
const subClient = pubClient.duplicate();
await Promise.all([pubClient.connect(), subClient.connect()]);
io.adapter(createAdapter(pubClient, subClient));
}
Redis Client Configuration#
Location: eve/apps/stream-service/src/redis.ts
import Redis from 'ioredis';
const redis = new Redis(process.env.REDIS_URL ?? 'redis://localhost:6379');
export async function connectRedis(): Promise<void> {
await redis.ping();
logger.info('Redis connected');
}
Caching Patterns#
| Service | Use Case | Key Pattern |
|---|---|---|
| User Service | Session cache | session:${sessionId} |
| Stream Service | Goal state | goal:${goalId} |
| Chat Service | Rate limiting | ratelimit:${userId}:${roomId} |
| Recommendation | Feature cache | features:${userId} |
Service-to-Service Integration#
Direct Service Calls#
Fan Club → Subscription Service#
Location: eve/apps/user-service/src/fanclub-service.ts
class FanClubService {
constructor(
private readonly subscriptionService: SubscriptionService
// ...other deps
) {}
async getPostAccess(userId: string, creatorId: string): Promise<boolean> {
const tiers = await this.subscriptionService.getCreatorTiers(creatorId);
const subscription = await this.subscriptionService.getCreatorSubscriptions(
creatorId,
userId
);
return this.subscriptionService.checkSubscriptionAccess(
subscription,
tiers
);
}
}
Chat → Moderation Integration#
Location: eve/apps/chat-service/src/moderation-integration.ts
class ModerationMiddleware {
constructor(private readonly moderationService: ModerationService) {}
async checkMessage(
userId: string,
roomId: string,
message: string
): Promise<'allowed' | 'shadow-banned' | 'blocked'> {
const isBanned = await this.moderationService.isBanned(userId, roomId);
if (isBanned) return 'blocked';
// Additional filtering logic...
return 'allowed';
}
}
// Socket integration
socket.data.moderationService = moderationService;
Data Flow Diagrams#
Real-Time Chat Flow#
┌──────────┐ ┌──────────────┐ ┌─────────────┐
│ Client │────►│ Socket.io GW │────►│ Chat Service│
│ (Web/App)│ │ (Port 5000)│ │ │
└──────────┘ └──────────────┘ └──────┬──────┘
│
┌──────────────────────┼──────────────────────┐
│ │ │
▼ ▼ ▼
┌───────────┐ ┌───────────┐ ┌───────────┐
│ MongoDB │ │ Redis │ │ Kafka │
│ (Persist) │ │ (Adapter) │ │ (Fan-out) │
└───────────┘ └─────┬─────┘ └───────────┘
│
▼
┌───────────────┐
│ Other Server │
│ Instances │
└───────┬───────┘
│
▼
┌───────────────┐
│ Target Client │
└───────────────┘
Streaming Flow#
┌──────────┐ ┌──────────────┐ ┌──────────────┐
│ Creator │────►│ Media GW │────►│ Stream Svc │
│ Encoder │ │ (WebRTC) │ │ (gRPC) │
└──────────┘ └──────────────┘ └──────┬───────┘
│
┌──────────────────────┼──────────────────────┐
│ │ │
▼ ▼ ▼
┌───────────┐ ┌───────────┐ ┌───────────┐
│PostgreSQL │ │ Redis │ │ Kafka │
│ (Metadata)│ │ (State) │ │ (Events) │
└───────────┘ └───────────┘ └─────┬─────┘
│
┌──────────────────────┘
│
▼
┌───────────────┐
│ Chat Service │
│ (Socket.io) │
└───────┬───────┘
│
▼
┌───────────────┐
│ Viewers │
└───────────────┘
Notification Flow#
┌──────────────┐ ┌──────────────┐ ┌──────────────────┐
│ Services │────►│ Notification│────►│ MongoDB │
│ (Any Event) │ │ Service │ │ (Persistence) │
└──────────────┘ └──────┬───────┘ └──────────────────┘
│
▼
┌───────────────┐
│ Socket.io │
│ Room Broadcast│
└───────┬───────┘
│
▼
user:${userId}:notifications
│
▼
┌───────────────┐
│ Connected │
│ Client(s) │
└───────────────┘
Analytics Pipeline#
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Services │────►│ Analytics │────►│ EventEmitter │
│ (REST POST) │ │ Ingestion │ │ Pipeline │
└──────────────┘ └──────────────┘ └──────┬───────┘
│
▼
┌───────────────┐
│ ClickHouse │
│ (Batch Write) │
└───────────────┘
Configuration Reference#
Environment Variables#
# Chat Service
CHAT_SERVICE_HOST=0.0.0.0
CHAT_SERVICE_PORT=5000
MONGODB_URI=mongodb://localhost:27017/eve
REDIS_URL=redis://localhost:6379
KAFKA_BROKERS=localhost:9092
# Stream Service
STREAM_SERVICE_HOST=0.0.0.0
STREAM_SERVICE_PORT=50051 # gRPC
STREAM_SERVICE_HEALTH_PORT=3001 # HTTP health
# User Service
USER_SERVICE_HOST=0.0.0.0
USER_SERVICE_PORT=3000
# Content Service
CONTENT_SERVICE_HOST=0.0.0.0
CONTENT_SERVICE_PORT=7001
# Analytics Service
ANALYTICS_SERVICE_HOST=0.0.0.0
ANALYTICS_SERVICE_PORT=7000
# Notification Service
NOTIFICATION_SERVICE_HOST=0.0.0.0
NOTIFICATION_SERVICE_PORT=7003
# Recommendation Service
RECOMMENDATION_SERVICE_HOST=0.0.0.0
RECOMMENDATION_SERVICE_PORT=7004
# Infrastructure
REDIS_URL=redis://localhost:6379
KAFKA_BROKERS=localhost:9092
MONGODB_URI=mongodb://localhost:27017/eve
DATABASE_URL=postgresql://user:pass@localhost:5432/eve
CLICKHOUSE_URL=http://localhost:8123
Service Port Summary#
| Service | Protocol | Port | Health Port |
|---|---|---|---|
| User Service | REST | 3000 | 3000 |
| Payment Service | REST | 4000 | 4000 |
| Chat Service | Socket.io | 5000 | 5000 |
| Analytics Service | REST | 7000 | 7000 |
| Content Service | REST | 7001 | 7001 |
| Moderation Service | REST | 7002 | 7002 |
| Notification Service | Socket.io | 7003 | 7003 |
| Recommendation Service | REST | 7004 | 7004 |
| Stream Service | gRPC | 50051 | 3001 |
Migration Considerations#
Protocol Mapping to Oshun#
| Eve Protocol | Oshun Equivalent | Notes |
|---|---|---|
| Socket.io | Socket.io | Maintain Redis adapter pattern |
| Kafka | @oshun/event-bus | Consider migration path |
| gRPC | gRPC | Maintain for high-throughput |
| REST | REST | Standardize on Fastify |
| Redis | @oshun/redis | Use shared client |
Communication Standardization#
- Event Envelope: Standardize on Oshun event envelope format
- Socket.io Namespaces: Prefix with
aphrodite:namespace - Kafka Topics: Prefix with
aphrodite.topic namespace - gRPC Package: Rename to
aphrodite.*packages
Document History#
| Date | Version | Author | Changes |
|---|---|---|---|
| 2026-01-16 | 1.0.0 | Claude | Initial communication architecture |